fplkit 2.4.0__tar.gz → 2.5.0__tar.gz

{fplkit-2.4.0 → fplkit-2.5.0}/.agents/TOOLS.md

@@ -24,43 +24,47 @@ which envelope you got. Warnings and progress go to stderr; the failure message
 in `error`, not on stderr. Full contract:
 [Command Reference](../docs/command-reference.md#json-output).
 
+Table mode is the mirror image: the table on stdout, and warnings, progress and the reason
+for a nonzero exit on stderr — so a script reading table output can silence the commentary
+with `2>/dev/null` without losing the table, whichever command it runs.
+
 ## CLI Commands
 
 | Command | Description | JSON | Format | Experimental | Pattern |
 |---------|-------------|------|--------|-------------|---------|
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
 | `status` | Show FPL gameweek status and upcoming deadlines. JSON `metadata` carries `gameweek`, `format` and `season` (hyphenated label, e.g. `2026-27`) - `season` is the directory segment skills must use when writing alongside fpl-cli's own reports | Yes | General | No | direct-api |
-| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs, the vaastav and Core-Insights datasets, Understat, and football-data.org, including that every club resolves across sources and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects). Exits non-zero when something is broken | Yes | General | No | direct-api |
+| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, reports whether the calibrated quality ceilings were measured against the newest completed season (the one season-derived artefact frozen in code, so a rollover with no recalibration leaves the scoring scale anchored to a cohort that has turned over), and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs, the vaastav and Core-Insights datasets, Understat, and football-data.org, including that every club resolves across sources and that players actually join by name (both Understat checks call the enrichment's own gate and matcher on the payload the scoring commands scan, so probe and runtime cannot disagree; a club resolving does not mean its players' names line up) and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects). Exits non-zero when something is broken | Yes | General | No | direct-api |
 | `fixtures` | Show fixtures for a gameweek. With custom analysis on, FDR is the venue-aware ATK/DEF mean `fpl fdr` and `fpl preview` show, so one match reads the same on all three; `-m/--mode` picks `difference` (default) or `opponent`, an unrated club scores a neutral 4.0 rather than the FPL API's 1-5 difficulty, and when the ratings cannot support difficulty at all, table mode warns on stderr and JSON adds a `team_ratings_unusable` entry to `metadata.warnings` (always present, empty or not). With it off, the raw FPL API 1-5 difficulty, and an explicitly passed `-m` reports on stderr that it does not apply. JSON `metadata` carries `custom_analysis`, `fdr_scale` (`team_ratings_1_7` / `fpl_api_1_5`) and `fdr_mode` (null when it does not apply) | Yes | General | No | direct-api |
-| `player` | Look up a player's stats, xG, ownership and fixture run. Before GW10 `quality_score` blends last season's pedigree in and JSON `metadata.warnings` says so (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), same as `fpl stats --value`. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
-| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Before GW10, `--value` quality scores blend last season's pts/90 pedigree with this season's observation and the command says so (stderr notice quoting the observation's weight band; JSON `metadata.warnings` code `early_season_prior_informed`); when last season's history cannot be loaded they are pure observation and the notice says that instead (`early_season_small_sample`, before GW6). GK ceilings scale with the calendar-possible sample, reaching full scale at GW6. Sortable by `ep_next`/`ep_this` (FPL predicted points; `ep_this` is only meaningful before the gameweek's first kickoff — FPL rolls it forward to `ep_next` as each player's match finishes); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction | Yes | General | No | direct-api |
-| `history` | Show historical player performance across seasons | Yes | General | No | direct-api |
+| `player` | Look up a player's stats, xG, ownership and fixture run. Before GW10 `quality_score` blends last season's pedigree in and JSON `metadata.warnings` says so (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), same as `fpl stats --value`; `understat_team_unmatched` joins it for any club Understat carried no players for, whose whole squad loses xG enrichment. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
+| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Before GW10, `--value` quality scores blend last season's pts/90 pedigree with this season's observation and the command says so (stderr notice quoting the observation's weight band; JSON `metadata.warnings` code `early_season_prior_informed`); when last season's history cannot be loaded they are pure observation and the notice says that instead (`early_season_small_sample`, before GW6). `understat_team_unmatched` is raised once per club Understat carried no players for, whose whole squad scores without xG. GK ceilings scale with the calendar-possible sample, reaching full scale at GW6. Sortable by `ep_next`/`ep_this` (FPL predicted points; `ep_this` is only meaningful before the gameweek's first kickoff — FPL rolls it forward to `ep_next` as each player's match finishes); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction | Yes | General | No | direct-api |
+| `history` | Show historical player performance across seasons. A provider that refuses exits 1 in both output formats, carrying the upstream's own reason: the error envelope used to say only `Failed to fetch historical data` while the cause went to stderr, and table mode printed the cause to stdout and exited 0 | Yes | General | No | direct-api |
 | `league` | Show live league standings for Classic and Draft leagues | No | General | No | direct-api |
 | `fdr` | Analyse fixture difficulty - easy runs, blanks, doubles. Three payloads, not one: the default call runs the agent and returns the full analysis plus `data.ratings_warning` (the team-ratings quality verdict, and with `--my-squad` also `data.predictions_stale` / `data.prediction_warnings` / `data.squad_exposure`); with custom analysis off it returns raw 1-5 FPL API difficulty (`data.easy_fixture_runs` only, `metadata.custom_analysis: false`, no ratings and so no warning); `--blanks` bypasses the agent for a schedule-only payload carrying neither the FDR analysis nor `ratings_warning`. `--blanks` mixes confirmed fixtures with predictions; when those predictions are stale, table mode warns on stderr and JSON adds a `fixture_predictions_stale` entry to `metadata.warnings` | Yes | General | No | via-agent |
-| `xg` | Analyse underlying stats: xG, xA, overperformers | Yes | General | No | via-agent |
+| `xg` | Analyse underlying stats: xG, xA, overperformers. The minutes floor and the window scale to the gameweeks played (`min(60 x window, 45 x gameweeks played)`, so 90 minutes over 2 GWs rather than an unreachable 360 over 6); the configured bar binds from GW9, or GW11 for `--all`. JSON `metadata` carries `window_label`, `gameweeks_played` and `min_minutes`, and `metadata.warnings` an `early_season_minutes_floor` notice while the bar is scaled, plus `understat_team_unmatched` for any club Understat carried no players for. When nothing qualifies, `data.empty_reason` says whether the floor (`below_minutes_floor`) or the data (`no_minutes_played`) caused it | Yes | General | No | via-agent |
 | `price-changes` | Show price changes and transfer activity | No | General | No | via-agent |
-| `price-history` | Show price trajectory and transfer momentum | Yes | General | No | direct-api |
-| `returnees` | Track injured and suspended players due back soon, so a returnee can be claimed in draft before they are fit or planned around in classic. Reads the FPL availability news, filters to returns inside a window (`--window N`, 1-38) and through a source-aware quality bar, and diffs against the stored watchlist for week-over-week changes. Most flagged players carry no parseable return date, so date-unknown entries are the norm rather than the exception; `--enrich` searches the web for fresher timing on those and on stale-news entries (needs a Perplexity key; skips with a note without one) and shows it beside the FPL news, never over it. `--all` bypasses the quality bar and deliberately does not persist the snapshot. JSON `metadata` carries `window`, `escalation_window`, `stash_upgrade_margin`, `transitions_available`, `quality_bar_available`, `quality_bar_applied` and `enrichment_requested`/`_available`/`_note`/`_count`/`_rate_limited` (true when the search provider rate-limited the run even after retrying — the one failure a re-run is likely to clear); `data` is `{entries, departures}`, each entry carrying `quality.basis`/`quality.meets_stash`, `expected_return`/`return_gameweek`/`return_source`, `escalation_eligible`/`escalation_basis`, `transition`, and `enrichment` (null unless enriched) | Yes | General | No | direct-api |
+| `price-history` | Show price trajectory and transfer momentum. A trend provider that refuses exits 1 in both output formats with the upstream's own reason — the error envelope used to say only `Failed to fetch price history data` while the table path named the cause | Yes | General | No | direct-api |
+| `returnees` | Track injured and suspended players due back soon, so a returnee can be claimed in draft before they are fit or planned around in classic. Reads the FPL availability news, filters to returns inside a window (`--window N`, 1-38) and through a source-aware quality bar, and diffs against the stored watchlist for week-over-week changes. Most flagged players carry no parseable return date, so date-unknown entries are the norm rather than the exception; `--enrich` searches the web for fresher timing on those and on stale-news entries (needs a Perplexity key; skips with a note without one) and shows it beside the FPL news, never over it. `--all` bypasses the quality bar and deliberately does not persist the snapshot. JSON `metadata` carries `window`, `escalation_window`, `stash_upgrade_margin`, `transitions_available`, `transitions_baseline_gameweek` (the gameweek `transition` is measured against — every run in a gameweek diffs against the last state stored before it, so a repeat run reports the same changes), `quality_bar_available`, `quality_bar_applied` and `enrichment_requested`/`_available`/`_note`/`_count`/`_rate_limited` (true when the search provider rate-limited the run even after retrying — the one failure a re-run is likely to clear); `data` is `{entries, departures}`, each entry carrying `quality.basis`/`quality.meets_stash`, `expected_return`/`return_gameweek`/`return_source`, `escalation_eligible`/`escalation_basis`, `transition`, and `enrichment` (null unless enriched) | Yes | General | No | direct-api |
 | `preview` | Run full pre-gameweek analysis and generate report. `--save` writes to `<output dir>/<season>/gw{N}-preview.md`; `--scout` writes to `<research dir>/ai-scout-reports/<season>/gw{N}-scout-preview[-referenced].md` | No | General | No | via-agent |
-| `review` | Review a completed gameweek - squad performance and standings. `--save` writes to `<output dir>/<season>/gw{N}-review.md`; `--compare-recs` reads `gw{N}-recommendations.md` from the same season directory | No | General | No | via-agent |
-| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`. Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name, club and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) and `first_capture_store_path` (always present; the partition directory on a first capture, `null` after). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped | Yes | General | No | via-agent |
+| `review` | Review a completed gameweek - squad performance and standings. `--save` writes to `<output dir>/<season>/gw{N}-review.md`; `--compare-recs` reads `gw{N}-recommendations.md` from the same season directory. Under `--summarise` the personal analysis is handed next gameweek's fixtures — every club's opponent and venue plus each squad player's positional FDR (1-7 team ratings with custom analysis on, the FPL API's 1-5 difficulty with it off, carrying the same scale footer and unrated-club caveat the FDR tables print, plus any warning that the ratings cannot support difficulty) — so its "Next Week" calls are grounded in fixtures rather than in one week of points; with no next gameweek to look at, that section is narrowed to fixture-independent observations and points at `fpl gw-prep`, and a gameweek already played is marked retrospective. The answer is then checked back against that block — a cited FDR the block never printed, or any fixture claim made without one — and against the sections its prompt asked for: an answer missing a `## ` heading, ending mid-sentence, or that the provider says it stopped early on is retried once, and a still-incomplete one is warned about on stderr (detail in `data/debug/synthesis_corrections.txt` under `--debug`) and carries the same list as a callout in the saved report. The summary is an add-on the review does not depend on: the two provider roles resolve independently, and a role with no usable key is skipped with the reason on stderr (`Community narrative skipped: ...` / `Personal analysis skipped: ...`) while the review prints, saves and exits 0 — so one key produces that half rather than nothing, and a saved report names each skipped half in a warning callout of its own. A gameweek it cannot resolve - one still being played, an id the season does not have, a season with nothing finished yet - is refused with the specific reason on stderr and exit 1; stdout carries the review or nothing | No | General | No | via-agent |
+| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`. Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. The club is not carried but *derived*, from the gameweek's own fixtures: FPL's live data records which fixtures each player's club played, so a double gameweek settles his club outright and a single narrows it to two, with one `element-summary` request spent only where today's club is absent from that pair (proof he has moved); today's club being one of the two is left unanswered rather than assumed, so a recorded club still wins there. That reaches the two cases a carry structurally cannot — a first capture and a coarse-to-detailed upgrade, neither of which has a recorded squad — and it supersedes a stale recorded club rather than preserving it, with `league_history_club_rederived` naming how many were replaced. A club that blanked has no fixture to intersect and falls back to the recorded club, then today's; name and position are not derivable from fixtures at all and stay carry-only. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. A rebuild likewise never writes away a league position or cumulative total it cannot re-derive: draft has no per-manager history endpoint and its standings describe a later gameweek, so a replayed draft gameweek keeps the figures already recorded (`league_history_standings_carried`) instead of nulling them, which used to cost the ledger every position that gameweek held and collapse the streaks built on them. Where they were already lost, every run restores them from the ledger itself — the superseded line, or a cumulative total re-summed from earlier gameweeks — with no flag and no request (`league_history_standings_repaired`); a draft gameweek's table is derivable from `gross_points` alone at the league's start gameweek. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) and `first_capture_store_path` (always present; the partition directory on a first capture, `null` after). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. A recap of the most recently finished gameweek keeps working once the next gameweek has started: the league table describes that later gameweek from its deadline onward, so the run takes the replay path (figures from each manager's own gameweek history, positions and cumulative totals derived rather than read off the table) and raises a `league_standings_moved_on` warning, instead of reconciling two different gameweeks' numbers against each other and exiting 1 with the ledger row unwritten. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped; an editorial the provider stopped early on is written out as it stands with the reason on stderr and a `synthesis_stopped_early` warning in JSON. A gameweek that cannot be resolved at all exits 1 in both output formats - it used to exit 1 under `--format json` with a generic `"Could not resolve a gameweek to recap."` and 0 in table mode - and the resolver's own reason (`Gameweek 7 is not yet finished`) now reaches the error envelope and the stderr prose alike. On the league's opening gameweek only (GW1, or its own `start_event`), each classic manager's FPL-wide prior-season record — seasons played, last season's points/rank/top-% finish, best season — is fetched from the manager-history endpoint (one request per manager, that gameweek only, and only with `--save`/`--output` or `--summarise`; a league created after GW1 shares the fetch with its league-start offset) and rendered as a `# Prior Seasons` report section and a locked `## Prior Seasons` prompt section with an explicit count; tenure is phrased FPL-wide because entry and league IDs are reissued each season, and a manager with no record or a failed fetch is named as such rather than omitted. Nothing of it reaches the ledger or the JSON rows; draft has no such endpoint and no such section | Yes | General | No | via-agent |
 | `league-fines` | Show who has been fined this season and how much of it was actually ruled, folded out of the league history ledger. Reads local files only - no network - so it works for any season still on disk (`--season 2025-26`). Nothing is re-ruled: a fine is counted exactly as its gameweek recorded it. Counts, never money (`penalty` is free text; settlement and escalation are not modelled). Every gameweek that could not be ruled is named beneath the table - never captured, unreadable, captured before rulings were recorded, captured with no rules configured, or captured at a fidelity that could not rule a given rule. `--format json` emits one entry per recorded manager, fined or not, each with `counts` (zero included), `total`, `fined_gameweeks`, `ruled_gameweeks`, `unruled_gameweeks`, `first_recorded_gameweek`, `last_recorded_gameweek` and `is_fully_ruled`; `metadata` carries `season`, `fpl_format`, `league_id`, `gameweek`, `start_gameweek`, `rule_types`, `total_fines` and `qualifiers`. Exits 1 with the shared error envelope when no league id is configured for the format | Yes | General | No | direct-api |
-| `captain` | Analyse and rank captain options for next gameweek. JSON candidates include `adjusted_npxg_per_90` and `raw_npxg_per_90` when fixture adjustment is active. Consistency tiebreaker (CV-xGI percentile) phased in GW6-10. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the GW1-9 shrinkage rather than pulled toward the position mean | Yes | Classic | Yes | via-agent |
-| `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the ownership, matchup and consistency bonuses stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), table mode prints it to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing | Yes | Classic | Yes | via-agent |
-| `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (CV-xGI percentile, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the matchup and consistency bonuses stay pure observation, and the score agrees with `fpl transfer-eval`'s Outlook column; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), table mode prints it to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing | Yes | Classic | Yes | via-agent |
+| `captain` | Analyse and rank captain options for next gameweek. Your squad is the default, so an absent `classic_entry_id` exits 1 with an `error` envelope naming `--global` rather than returning the global list as though it were your options; `metadata.my_squad_mode` says which list the payload holds, and `metadata.warnings` carries `captain_global_fallback` when there is no squad to rank yet (before the first deadline) or `captain_no_next_gameweek` when there is no next gameweek at all (finished season, or the next one unpublished). An entry ID that does not resolve is a failure, not a fallback, worded exactly as `squad` words it (`get_own_squad_picks`, `agents/common.py`). JSON candidates include `adjusted_npxg_per_90` and `raw_npxg_per_90` when fixture adjustment is active. Consistency tiebreaker (CV-xGI percentile) phased in GW6-10. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the GW1-9 shrinkage rather than pulled toward the position mean | Yes | Classic | Yes | via-agent |
+| `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the ownership, matchup and consistency bonuses stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) plus `understat_team_unmatched` for any club Understat carried no players for, table mode prints them to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. The gameweek stamped into JSON `metadata` is fetched after the agent succeeds, not before it runs, so an unreachable API is reported as the agent's failure in both output formats rather than as a client error under `--format json` and an agent error in table mode | Yes | Classic | Yes | via-agent |
+| `targets` | Find transfer targets - high performers across all ownership. Consistency bonus (CV-xGI percentile, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the matchup and consistency bonuses stay pure observation, and the score agrees with `fpl transfer-eval`'s Outlook column; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) plus `understat_team_unmatched` for any club Understat carried no players for, table mode prints them to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing | Yes | Classic | Yes | via-agent |
 | `transfer-eval` | Compare transfer OUT player against IN candidates. JSON includes `adjusted_npxg_per_90` and `raw_npxg_per_90` per player when fixture adjustment is active. Before GW10 `quality_score` carries the value family's prior blend (matching `fpl player` and `fpl stats --value`) and `target_score` the target family's (matching `fpl targets`); the single-GW `lineup_score` keeps position-mean shrinkage. JSON `metadata.warnings` carries the early-season notice naming both blended columns, or only `target_score` when no Understat match produced a quality score. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of whichever device applies, rather than pulled toward the position mean or handed last season's standing. A name two players answer to exactly (`Henderson`) exits 1 with an `error` envelope naming both, rather than resolving to whichever the API lists first; `Name (TEAM)` or a player ID picks one | Yes | General | Yes | via-agent |
-| `allocate` | Select mathematically optimal 15-player squad within budget. At `--horizon >= 2` the solver ranks on the value family's GW1-9 prior blend (last season's pedigree weighted by confidence); players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of it rather than handed last season's standing, and stay in the solver pool; JSON `metadata.warnings` carries the early-season notice at `--horizon >= 2` (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) | Yes | Classic | Yes | direct-api |
-| `waivers` | Show waiver recommendations for your draft league. JSON `data` carries `top_targets` and `targets_by_position` (ranked claims) plus `pool` — the full unowned roster, one `{id, player_name, position, team_short}` row each, unranked and untruncated, so a consumer can answer "is this player claimable at all" without inferring it from the ranked lists. Keeper scores carry the GK signal block (saves/90, defensive quality, clean-sheet rate), read from the main-game player each draft element is joined to on `code` because the draft bootstrap publishes none of it, so draft keepers rank on what separates them rather than on form and ppg alone. Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage; the matchup, position-need, team-stacking and consistency terms stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live, and reports `early_season_small_sample` both when history could not be loaded and when no draft element found a main-game counterpart to take a prior from. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing | Yes | Draft | Yes | via-agent |
-| `squad` | Analyse your FPL squad health and fixtures. Exits 1 with an `error` envelope when no entry ID is configured for the active format | Yes | General | No | via-agent |
-| `squad grid` | Show squad fixture difficulty grid. Exits 1 with an `error` envelope when no entry ID is configured for the active format, or when the squad fetch fails. A `--watch` name that does not resolve is non-fatal either way: unmatched, or matching two players exactly, it warns on stderr and is skipped, and the grid still renders | Yes | General | No | via-agent |
+| `allocate` | Select mathematically optimal 15-player squad within budget. At `--horizon >= 2` the solver ranks on the value family's GW1-9 prior blend (last season's pedigree weighted by confidence); players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of it rather than handed last season's standing, and stay in the solver pool; JSON `metadata.warnings` carries the early-season notice at `--horizon >= 2` (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), plus `understat_team_unmatched` for any club Understat carried no players for, whose squad therefore scored without xG | Yes | Classic | Yes | direct-api |
+| `waivers` | Show waiver recommendations for your draft league. JSON `data` carries `top_targets` and `targets_by_position` (ranked claims) plus `pool` — the full unowned roster, one `{id, player_name, position, team_short}` row each, unranked and untruncated, so a consumer can answer "is this player claimable at all" without inferring it from the ranked lists. Keeper scores carry the GK signal block (saves/90, defensive quality, clean-sheet rate), read from the main-game player each draft element is joined to on `code` because the draft bootstrap publishes none of it, so draft keepers rank on what separates them rather than on form and ppg alone. Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage; the matchup, position-need, team-stacking and consistency terms stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live, and reports `early_season_small_sample` both when history could not be loaded and when no draft element found a main-game counterpart to take a prior from. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. No `draft_league_id` configured exits 1 in both output formats — table mode used to warn and exit 0 | Yes | Draft | Yes | via-agent |
+| `squad` | Analyse your FPL squad health and fixtures. Exits 1 with an `error` envelope when no entry ID is configured for the active format. `--classic` / `--draft` (mutually exclusive) pin the format instead of inferring it from the configured IDs, so a caller that means classic gets the missing-ID error rather than the draft roster; with neither, single-format configs still auto-select. A picks 404 is checked against `entry/<id>/` before it is reported as "no squad submitted yet", so a reissued or wrong entry ID says so; `squad grid` and `captain` share that diagnosis through `agents/common.py` | Yes | General | No | via-agent |
+| `squad grid` | Show squad fixture difficulty grid. Exits 1 with an `error` envelope when no entry ID is configured for the active format, or when the squad fetch fails. Takes the same `--classic` / `--draft` pinning as `squad`, before or after the subcommand, and the same stale-entry diagnosis. A `--watch` name that does not resolve is non-fatal either way: unmatched, or matching two players exactly, it warns on stderr and is skipped, and the grid still renders | Yes | General | No | via-agent |
 | `squad sell-prices` | Show squad sell prices and financial breakdown. Nothing cached and no `--refresh`, a failed scrape, draft format, or a scrape the extraction heuristics distrust each exit 1 with an `error` envelope under `--format json`; table mode still renders a suspect scrape under a `Squad Budget (Suspect)` panel, since a reader can judge it and `fpl allocate --sell-prices` cannot | Yes | Classic | No | direct-api |
 | `chips` | View and plan FPL chip usage | Yes | Classic | No | direct-api |
-| `chips timing` | Recommend chip timing based on blank/double GW exposure | Yes | Classic | No | via-agent |
+| `chips timing` | Recommend chip timing based on blank/double GW exposure. No `classic_entry_id` configured, and no completed gameweek to measure exposure against, each exit 1 in both output formats — table mode used to print the reason and exit 0. The missing-ID message is the shared one `fpl squad` and `fpl squad grid` give, and a failed fixture agent reports the agent's own reason in the same words either way (`Fixture agent failed: <reason>`), where the envelope and the terminal used to word it differently and neither passed the reason on | Yes | Classic | No | via-agent |
 | `chips add` | Plan a chip for a gameweek | No | Classic | No | direct-api |
 | `chips remove` | Remove a planned chip from a gameweek | No | Classic | No | direct-api |
 | `chips sync` | Sync chip usage from FPL API | No | Classic | No | direct-api |
 | `ratings` | Display team ratings | No | General | Yes | direct-api |
-| `ratings update` | Recalculate ratings from fixture results (shrunk toward the previous-season prior before GW12; seeds from the prior when no results exist yet) | No | General | Yes | direct-api |
+| `ratings update` | Recalculate ratings from fixture results (shrunk toward the previous-season prior before GW12; seeds from the prior when no results exist yet). Wherever it applies the prior it names the clubs rated from Championship results or the flat promoted estimate — with the remedy attached where no `FOOTBALL_DATA_API_KEY` is set — and points at `team_ratings_prior.yaml`, whose `inputs` block records each club's basis, matches and the rates it was ranked on. The prior rebuilds itself when an input it went without becomes available; `--refresh-prior` forces it | No | General | Yes | direct-api |
 | `intel` | Show season preview intel collected per team, with coverage and per-gameweek decay. JSON `metadata` carries `coverage.usable_as` (`full` / `negative_filter_only` / `none`), `section_confidence`, `sections_live`/`sections_expired`, `decay_schedule`, `team_set_warning` and `warnings`. `-g/--gameweek` ages the payload to any gameweek; `--show-decay` prints the expiry schedule | Yes | General | No | direct-api |
 | `intel schema` | Print the preview file format with every field explained | No | General | No | direct-api |
 | `intel init` | Scaffold an empty preview file per Premier League team (`--force` overwrites). Stubs never count toward coverage | No | General | No | direct-api |
@@ -92,6 +96,7 @@ Skills write their own outputs (`gw{N}-recommendations.md`, `gw{N}-squad-builder
 | release-notes | `skills/release-notes/` | Draft release notes and suggest the next semver (read-only preview; never tags or publishes) | Full: Claude Code, Codex, Cursor, Copilot |
 | release | `skills/release/` | Cut a release end-to-end: preflight, notes via release-notes, approval gate, publish GitHub release (tag drives PyPI publish + changelog automation) | Full: Claude Code (local), Codex, Cursor, Copilot. Partial: Claude Code web (publish step handed to user) |
 | create-pr | `skills/create-pr/` | Open a PR for the current branch: conventional-commit title (the changelog line) + why-first prose body in the fpl-cli PR description style | Full: Claude Code, Codex, Cursor, Copilot |
+| build-test-plan | `skills/build-test-plan/` | Build a runnable test plan for the user-facing changes shipped between two releases, written for a live-data session in the fpl-workspace vault (deep per-change research, carries forward the previous plan's BLOCKED/FAIL items) | Full: Claude Code (parallel research sub-agents). Partial: Codex, Cursor, Copilot |
 
 ## Analysis Agents
 
@@ -116,11 +121,13 @@ Python classes in `fpl_cli/agents/` that implement `async run(context) -> AgentR
 - Every scoring family holds players known not to be playing out of its GW1-9 early-season device — the prior blend for the value family (`quality_score`, `fpl allocate`) and the ownership family (`targets`, `differentials`, `waivers`, transfer-eval's Outlook), position-mean shrinkage for the single-GW family (`captain`, `bench-order`, `starting-xi`, transfer-eval's This GW); bench and lineup order on raw scores, so for those two it changes the displayed score only
 - TransferEvalAgent is used by both `transfer-eval` CLI command and gw-prep skill
 - `bench_order.py`, `starting_xi.py` and `transfer_eval.py` (`.agents/skills/gw-prep/scripts/`) take player names, accept the `Name (TEAM)` disambiguator, and exit 1 naming both candidates when a name matches two players exactly (Dean and Jordan Henderson are both `Henderson`) rather than resolving to whichever the API lists first. Pass `Name (CLUB)` from the squad grid's `player`/`team` pair (issue #180). All three share that resolution with the `transfer-eval` CLI command through `resolve_player_or_report` / `resolve_players_or_report` (`fpl_cli/models/player.py`)
+- Every gw-prep script that runs an agent (`bench_order.py`, `starting_xi.py`, `transfer_eval.py`) runs it inside `json_output_mode()`, so a phase can parse stdout from byte 0 on the success path as well as the failure one. Until #226 the agent's two progress lines landed ahead of the payload and only the error envelopes were clean — the reverse of what a lenient reader would guess. `Agent.log` now writes to stderr for every agent, so the same holds for `fpl transfer-eval --format json`; `tests/test_cli_json_contract.py` guards all four
 - `extract_classic_squad.py` (`.agents/skills/gw-prep/scripts/`) — deterministic Classic Squad block extractor used by gw-prep Phase A3 + Phase E. JSON stdout; read-only; emits TypedDict-annotated payloads.
 - gw-prep Phase B10 runs `fpl returnees --enrich --format json` and inlines the payload into both Phase C prompts, rendering a Returning Soon section in the classic and draft output templates. In draft a row can escalate into a stash claim; in classic the watchlist is informational and transfer recommendations may not name a tracked returnee (`references/rules.md`)
 - gw-prep Phase B1 and squad-builder Phase B each run the `fpl fdr` analysis call alongside `fpl fdr --blanks --format json`, and read the quality signals both return -- `data.ratings_warning`, `metadata.custom_analysis`, the blanks payload's `metadata.warnings`, plus `data.predictions_stale` / `data.prediction_warnings` where `--my-squad` resolved a squad. `--blanks` bypasses the fixture agent for a schedule-only payload carrying none of the analysis and none of those fields, so the skills that issued only it were promising pFDR they never received (gw-prep's pFDR Overview, squad-builder's per-position `{ATK|DEF} column` blocks) and silently accepting whatever rating quality they got (issue #135). Whatever fires becomes `data_caveat`, inlined into every sub-agent prompt and written to the output's Data Quality section, messages quoted verbatim so the remedy they name (`fpl ratings update`, `fpl init`) survives. gw-prep passes `--my-squad` (it also wants squad blank/double exposure); squad-builder deliberately does not, since it is replacing the 15 and its season-start modes have no squad to resolve. Enforced by `tests/test_skill_fdr_quality_signals.py`
-- gw-prep Phase B8 and squad-builder Phase B derive the `fpl stats --min-minutes` floor from the current gameweek (`min(cap, (N - 1) * 45)`, caps 315/450) rather than hardcoding it. A fixed floor is unreachable until GW8/GW11 and empties the result silently -- `fpl stats` returns a well-formed envelope with `"data": []`. Both also rank on `ep_next` before GW6 -- the positional sorts (xGI, form, total_points, ppg) order mostly on sample that early -- and label each block with the sort and floor it used, so a downstream agent reads the ordering as a projection rather than as observed output; an empty block is annotated rather than left bare. Enforced by `tests/test_skill_stats_thresholds.py`
+- StatsAgent (`fpl xg`, `fpl preview`) clamps its own window and minutes floor to the gameweeks played, scaling the floor by the same 45 minutes per gameweek the skills apply to `fpl stats --min-minutes` below -- off a different anchor, though: the skills scale off `(N - 1)` for the upcoming gameweek, this off the gameweeks the API reports finished, which diverges under a postponement and only downwards. The default 360-minute floor is arithmetically impossible until four gameweeks have finished and out of reach for all but ever-presents for several more, so it emptied every table through the opening weeks (issue #227); the configured bar binds again from 8 finished gameweeks, 10 for `--all`. `data.min_minutes` / `data.gameweeks_played` / `data.window_label` report what was applied, `data.empty_reason` says whether the floor or the data emptied the result, and `warnings` carries `early_season_minutes_floor` while the bar is scaled. A floor a caller passes explicitly (`fpl targets --min-minutes`, `fpl differentials --min-minutes`) is applied verbatim. Every surface renders the reason where its reader is: `fpl xg`, `fpl targets` and `fpl differentials` in place of their tables, `fpl preview` under a Performance Stats heading that now carries the analysed window rather than a hardcoded six gameweeks (console, `templates/gw_preview.md.j2`, and ReportAgent's inline fallback alike). Enforced by `tests/test_stats.py::TestStatsAgentMinutesFloor` and `::TestStatsAgentWindowPrefilter`
+- gw-prep Phase B8 and squad-builder Phase B derive the `fpl stats --min-minutes` floor from the current gameweek (`min(cap, (N - 1) * 45)`, caps 315/450) rather than hardcoding it. A fixed floor is unreachable until GW8/GW11 and empties the result silently -- `fpl stats` returns a well-formed envelope with `"data": []`. Both also rank on `ep_next` before GW6 -- the positional sorts (xGI, form, total_points, ppg) order mostly on sample that early -- and label each block with the sort and floor it used, so a downstream agent knows what ordered it; an empty block is annotated rather than left bare. Both also say what that sort is *not*: before FPL's fixture factor moves off 1.0, `ep_next` tracks `form` almost exactly (at GW4, every row of all four positional shortlists), so the ordering is a form ordering with doubtful players scaled down by chance of playing, and a sub-agent must not be told it is a projection rather than observed output (issue #236). Enforced by `tests/test_skill_stats_thresholds.py`
 - `validate_draft_waivers.py` (`.agents/skills/gw-prep/scripts/`) — cross-checks the Draft waiver table against the live waiver pool and squad grid (gw-prep Phase D1). JSON stdout; read-only; exits 0 whatever the validation finds — the one non-zero exit is the startup guard below.
 - `normalise_entities.py` (`.agents/skills/gw-prep/scripts/`) — decodes HTML-escaped text in a report assembled from sub-agent output and reports the entity references it deliberately leaves alone. JSON stdout; rewrites its `--file` in place; shared by gw-prep Phase D, squad-builder Phase E and update-gw-prep Phase D, all of which warn rather than block on its findings. Contract and warn posture live once, in `.agents/skills/gw-prep/references/entity-normalisation.md`.
-- Every script under `.agents/skills/gw-prep/scripts/` imports the `fpl_cli` package, so it runs on the interpreter fpl-cli is installed on — gw-prep's SKILL.md writes that interpreter as `[YOUR_PYTHON]` (squad-builder and update-gw-prep still spell their `normalise_entities.py` call `python3`, correct only under an activated venv). A standalone `fpl` on `PATH` (uv tool, pipx) provides the command but not the package; `_bootstrap.py` catches that case ahead of the fpl_cli imports and exits 1 with `{"error": true, "messages": [...]}` on stdout, which the phases parsing that stdout surface as a warning instead of a traceback
+- Every script under `.agents/skills/gw-prep/scripts/` imports the `fpl_cli` package, so it runs on the interpreter fpl-cli is installed on — every SKILL.md that calls one (gw-prep, squad-builder, update-gw-prep) writes that interpreter as `[YOUR_PYTHON]`, and squad-builder/update-gw-prep reach gw-prep's `scripts/` cross-skill via `[YOUR_SKILLS_DIR]` since `${CLAUDE_SKILL_DIR}` resolves to the *calling* skill's own directory (issue #221). A standalone `fpl` on `PATH` (uv tool, pipx) provides the command but not the package; `_bootstrap.py` catches that case ahead of the fpl_cli imports and exits 1 with `{"error": true, "messages": [...]}` on stdout, which the phases parsing that stdout surface as a warning instead of a traceback
 - The extractor and the waiver validator locate markdown sections via `fpl_cli.utils.markdown` (`HeadingMatcher`, `find_section`, `section_body`, `leaf_body`, `fence_flags`), tolerating LLM heading drift (qualifiers, case, leading annotations, opt-in aliases) without matching a different heading that shares a prefix. Also used by `fpl_cli/prompts/review.py` for the GW Narrative section boundary.

fplkit-2.5.0/.agents/skills/build-test-plan/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: build-test-plan
+description: >
+  Build a runnable test plan covering every user-facing fpl-cli change
+  shipped between two releases, written for a Claude Code session in the
+  fpl-workspace vault (live FPL API, real leagues, LLM keys). Use whenever
+  the user says "build a test plan", "test plan for the release", "what
+  needs testing since v2.2", "verify the last release", or asks how to
+  check that shipped changes actually work against live data. Also the
+  natural follow-up after cutting a release — offer it once a release is
+  published.
+model: opus
+compatibility:
+  claude-code: full (parallel research sub-agents; GitHub MCP on the web, gh locally)
+  codex: partial (sequential research — no sub-agent spawning)
+  cursor: partial (sequential research)
+  copilot: partial (sequential research)
+---
+
+<!-- Runs in the fpl-cli repo; writes into the fpl-workspace vault. -->
+
+# Build Test Plan
+
+Turn a range of fpl-cli releases into a runbook another Claude Code
+session can execute against live data in the fpl-workspace vault.
+
+This skill runs **in the fpl-cli repo**, where the git history, PR bodies,
+diffs and docs live. The plan it writes runs **in fpl-workspace**, which is
+where the FPL credentials, LLM keys, real leagues and generated data are.
+That split is the whole reason the plan has to be written down rather than
+improvised: the session that knows what changed is not the session that can
+exercise it.
+
+Two things stay true throughout:
+
+- **The plan targets released `fplkit`.** The vault installs the CLI from
+  PyPI, so a test written against an unreleased commit on `main` cannot be
+  run there. Unreleased work is noted, not tested.
+- **fpl-cli is public; the vault is private.** The plan lives in the vault,
+  but write it so it *could* be public: no manager or league names, no
+  entry/league IDs. Refer to `classic-<league id>`, "your classic league".
+  Real names belong only in the Results log the runner fills in.
+
+## Step 1 — Fix the range
+
+```bash
+git fetch origin main --tags
+git tag --sort=-creatordate | head -10
+```
+
+The default range is **the end of the last test plan → the newest release
+tag**. Find where the last one stopped:
+
+```bash
+ls /home/user/fpl-workspace/docs/test-plans/
+```
+
+If the vault isn't cloned, attach `rossgroomio/fpl-workspace` and clone it
+— the plan lands there and the environment facts come from there.
+
+Then classify what sits beyond the newest tag:
+
+```bash
+git log <newest tag>..origin/main --oneline --no-decorate
+```
+
+If those commits are `docs:`/`chore:`/`ci:` only, say so in the plan's
+opening paragraph — it tells the runner that testing the released version
+covers the whole range, which is worth stating because it is not obvious.
+If unreleased *code* sits on main, the honest options are to cut a release
+first or to scope the plan to the released range and list the unreleased
+work as untested. Put that to the user rather than silently picking.
+
+Confirm the range with the user before researching. Getting it wrong wastes
+the most expensive step.
+
+## Step 2 — Inventory the changes
+
+```bash
+git log <from>..<to> --oneline --no-decorate
+sed -n '/## \[<to version>\]/,/## \[<from version>\]/p' CHANGELOG.md
+```
+
+Squash-merged subjects carry their PR number as `(#N)` — that is the handle
+for the research step.
+
+Keep `feat:`, `fix:`, `refactor:`, `perf:`. Drop `chore:`/`docs:`/`ci:`/
+`test:`/`style:` — but skim their subjects first. A user-visible change
+mislabelled `chore:` is invisible to the changelog *and* to this plan, and
+that is exactly the change nobody thinks to test.
+
+## Step 3 — Carry forward the unfinished business
+
+Two sources feed this, and a plan that reads only the first will miss work
+the user has already specified.
+
+### The previous plan's Results log
+
+Three kinds of thing carry forward:
+
+- **BLOCKED tests** — deferred because the season state didn't allow them
+  ("only GW1 complete, defer the replay test"). Check whether the condition
+  has since cleared. If it has, the test is now runnable and belongs in the
+  new plan verbatim.
+- **FAILs** — check whether the range under test fixes them. Match on PR
+  subject and number: a FAIL that a shipped `fix:` claims to address needs
+  a test that reproduces the *original* failure and confirms it is gone.
+  A FAIL nothing has addressed carries forward unchanged, so it doesn't
+  quietly become accepted behaviour.
+- **Post-plan findings** — the observations recorded below the table. These
+  are usually the sharpest bugs in the whole document, because they came
+  from a human looking at real output. Same treatment as FAILs.
+
+This loop is real: most of v2.3.0 exists because the v2.0→v2.2 run found
+those bugs. A plan that doesn't close its predecessor's loop lets fixes ship
+unverified.
+
+Carry the *substance* across, not a pointer to it. A runner who has to open
+the previous plan to understand a test has been handed two documents to
+execute instead of one, and mid-run is the worst moment to go looking. So
+state what the old test found and what changed, inline, in the new test.
+
+Plans all live together in `docs/test-plans/`, so where provenance is
+genuinely useful — tracing a claim, or flagging that this plan contradicts
+its predecessor — name the file (`v2.0-to-v2.2.md`) and let co-location do
+the rest. No paths, no links.
+
+### The vault's open issues
+
+The Results log records what a run found. The vault's issue tracker records
+what the user decided to do about it, which is not the same set — and it is
+where deferred testing work actually queues:
+
+```
+mcp__github__issue_read / list_issues on rossgroomio/fpl-workspace,
+state OPEN — the `testing` label first, then the rest
+```
+
+**Read the comments, not just the body.** A deferred-items issue grows by
+comment as later sessions hit the same wall, and the comments carry the
+best material in the whole tracker: fully-specified tests with the exact
+invocation and expected values, the data state at the time of testing, and
+the condition that would unblock each one. Fold those in close to as
+written — they are better specified than anything drafted fresh, and the
+person who wrote them was looking at real output.
+
+Two things to notice while you're there:
+
+- **Tests with no home.** Work deferred from a version that never got its
+  own plan has nowhere to be logged, and the issue usually says so. The
+  plan you are writing is that home if its range covers the change.
+- **Environment blockers.** An open issue about the vault's own setup — a
+  broken helper script, a wrong interpreter, a missing key — is not a
+  change under test, but it will make a test fail confusingly and get
+  misattributed to fpl-cli. Surface those in the preflight.
+
+Cite the issue number against each carried test (`carried from
+workspace#34`), and have the wrap-up tell the runner to close those items
+as they are recorded. An issue that stays open after its tests pass is how
+the same work gets queued twice.
+
+## Step 4 — Research each change
+
+This is where plan quality is won or lost. A test built from a commit
+subject alone reads "verify `fpl doctor --providers` works" and cannot
+fail. A test built from the diff reads "expect all six probes, each
+asserting shape **and** volume: 20 teams, 38 gameweeks, every stat field
+the tool reads present" — and that one catches a regression.
+
+**Group before you fan out.** Cluster the commits by the surface they touch
+(league-recap and its ledger; `doctor`; scoring and data quality; JSON
+envelopes). Themes make better research units than individual PRs, because
+several PRs usually move one surface together and the tests want to be
+written against the surface's final state, not each intermediate step.
+
+Then spawn one research sub-agent per theme, in a single batch so they run
+concurrently. Brief each one:
+
+> Research the fpl-cli changes in <theme> shipped between <from> and <to>,
+> so a tester with a live FPL account can verify them. Commits: <list with
+> PR numbers>.
+>
+> For each change, read: the PR body and any linked issue (via GitHub MCP
+> `pull_request_read` / `issue_read`, or `gh pr view <N>`), the diff
+> (`git show <sha>`), the relevant section of `docs/command-reference.md`,
+> and the tests the PR added under `tests/`.
+>
+> Report back, per change:
+> - The exact CLI invocation that exercises it, flags included.
+> - Falsifiable expectations — specific counts, field names, value ranges,
+>   exit codes, which stream output lands on. Name the actual values
+>   (how many probes, which warning codes, which JSON keys), not "the
+>   documented ones".
+> - The repro from the issue, for a `fix:` — the condition that used to
+>   break is what the test recreates.
+> - Degradation and edge paths the change introduces or touches: missing
+>   data, corrupt file, unreachable provider, invalid input, exit codes.
+> - Whether the current season state can exercise it at all, and if not,
+>   the condition that would unblock it.
+>
+> Ground every specific in a file you actually read. Do not describe
+> behaviour you inferred from a commit subject.
+
+Sub-agent findings are a draft, not the plan. Reconcile them yourself:
+drop duplicates where two themes touch the same command, and check that
+the specifics they quote really appear in the docs or diff before those
+numbers become assertions the runner will trust.
+
+## What makes a test worth writing
+
+The reference plan (`docs/test-plans/v2.0-to-v2.2.md` in the vault) is the
+quality bar. What separates its useful tests from filler:
+
+**It can fail.** Every expectation is something that would read differently
+if the fix regressed. "Renders without crashing" is worth one line for a
+crash fix and nothing otherwise; "row count equals the real league size"
+caught a real pagination bug.
+
+**It tests the bug, not the fix.** For a `fix:`, recreate the condition
+from the issue and assert the old symptom is absent. Testing that the new
+code path runs tells you nothing about whether the bug is gone.
+
+**It uses the observable surface.** The runner has a released binary, not
+the source. Commands, files on disk, exit codes, stdout vs stderr — never
+internal functions.
+
+**It writes nothing into the vault the run wouldn't have written anyway.**
+The vault is someone's working record, not a scratch pad. `01_Reports/`
+holds point-in-time snapshots — the gameweek as it was analysed at the
+time — so a test that regenerates one overwrites the record with a later
+model's output, and a test that saves a preview for a gameweek whose
+deadline has not passed creates a file that should not exist yet. Both
+land in a PR as noise the author then has to spot and revert, which has
+happened on more than one run.
+
+So: every `--save` you write into a plan carries `-o <scratch>/reports`.
+`preview`, `review` and `league-recap` all take `-o/--output`, and the
+report is just as assertable from a scratch path — you are checking its
+content, not its location. Where a test must assert the *default* path is
+used, assert it on a scratch `HOME`/cwd rather than by writing into the
+real tree.
+
+The same discipline covers `data/`: the ledger under
+`data/league_history/` is the one thing worth capturing for real, because
+its rows are append-only and cannot be reconstructed once the season moves
+on. Everything else there — `returnee_snapshot.json`, `team_ratings*.yaml`,
+`team_finances.json` — is regenerable state the CLI rewrites, so a test
+that migrates or rewrites one points `FPL_CLI_DATA_DIR` at a throwaway
+copy. A migration performed as a side effect of a test is not a change
+anyone decided to make, and it reads in review as if it were.
+
+The question to ask of every artifact a plan produces: *would this have
+been created anyway, by real use, today?* If no, it goes to scratch.
+
+**It builds a fixture before it gives up.** When live data can't reach a
+code path, a scratch fixture often can: point `FPL_CLI_DATA_DIR` at a
+throwaway copy of the store and doctor a row to the shape the bug needed,
+or feed the matching function inputs that disagree. This reaches repair
+and migration paths that a healthy live store never exercises, and it
+costs the runner a `cp -r` they throw away afterwards. Reach for it before
+reaching for BLOCKED — and keep it off the real store, which for the
+ledger is irreplaceable.
+
+**It mines the environment for fixtures it already has.** The vault's own
+data is full of them. Players in captured ledger rows who have since
+changed club are a ready-made test that a re-run doesn't restamp recorded
+history — verify what each row *should* say from that gameweek's live
+data, tabulate it, and any drift is an unambiguous FAIL. Look for this
+before inventing setup.
+
+**It says when it genuinely can't run.** Some things no fixture reaches:
+a blank gameweek that hasn't happened, a week-over-week comparison with no
+prior week. Write the test anyway, mark it BLOCKED with the condition that
+unblocks it, and the next plan picks it up via Step 3. A test that
+silently can't run is worse than one marked BLOCKED, because it looks like
+coverage.
+
+**It covers degradation.** Missing config, corrupt store, provider down,
+bad gameweek number. Make corruption tests reversible and say how to
+restore (`git checkout -- <path>`) — the runner is working on real data
+they want to keep.
+
+**It names the channel.** This tool's JSON contract has moved between
+stdout and stderr more than once. Where a test asserts on output, say which
+stream, and have the runner capture stderr separately
+(`2>/tmp/<id>-err.txt`).
+
+**It earns its place.** Plan length tracks the range. Two releases and
+twenty user-facing changes justify something like the reference plan's
+~35 tests across four parts; a patch-only range with four fixes wants six
+or seven. Padding a small range with smoke tests of untouched commands
+buys no coverage and teaches the runner to skim.
+
+## Step 5 — Order the parts
+
+Group tests into parts by surface, then order the parts by **what the user
+gets from running them**, not by release order:
+
+1. Anything that produces artifacts worth having this week (a recap, a
+   ledger capture) goes first, because a plan often gets run across two
+   sessions and the first session should produce the thing with a deadline.
+2. Health checks next (`fpl doctor`) — they surface environment problems
+   that would otherwise show up as confusing failures later.
+3. Everything else, grouped by surface.
+
+Say the ordering rationale in the preamble. A runner who understands why
+Part 1 is first will keep it first when the session runs short.
+
+Number tests with a per-part letter prefix (`P1`–`P4` preflight, `R1`–`R10`
+recap, `D1`–`D4` doctor…) so the Results log stays readable and a follow-up
+session can reference a single test unambiguously.
+
+## Step 6 — Write the plan
+
+Read `references/plan-template.md` for the exact document shape, and
+`references/workspace-env.md` for the environment facts that go into the
+preflight and the cost/safety notes. Write the plan to:
+
+```
+/home/user/fpl-workspace/docs/test-plans/v<from>-to-<to>.md
+```
+
+Name it for the range's ends. Trim a trailing `.0` only when the two ends
+differ in major.minor — `v2.2.0`→`v2.4.0` becomes `v2.2-to-v2.4.md`,
+matching `v2.0-to-v2.2.md`. When both ends sit in the same minor, keep
+full patch versions on both, or the name reads as a range it isn't
+(`v2.3.0`→`v2.3.2` is `v2.3.0-to-v2.3.2.md`, never `v2.3-to-v2.3.2.md`).
+
+Pre-seed the Results log with one empty row per test ID. It is the runner's
+worksheet and the next plan's Step 3 input, so every ID needs a row waiting
+for it.
+
+Then add a **coverage map**: every in-range PR number against the test IDs
+that exercise it. Write it by walking the Step 2 inventory, not by
+summarising what you already wrote — the point is to catch the change you
+researched and then lost track of while grouping. A PR with no test ID
+next to it is either a gap to fill or a deliberate omission to justify in
+one line, and either way the runner can see it. This is cheap to produce
+and the only mechanism that makes coverage auditable from the artifact
+itself.
+
+Vault convention: no blank lines before or after headings.
+
+## Step 7 — Land it
+
+Commit the plan in the vault on its own branch:
+
+```bash
+cd /home/user/fpl-workspace
+git checkout -b claude/test-plan-v<to>
+git add docs/test-plans/<file>
+git commit -m "docs: add v<from> to v<to> test plan"
+```
+
+Ask before pushing — the vault is the user's own repo and they may want to
+read the plan first.
+
+Then summarise here: the range, how many tests in how many parts, which
+carried forward from the last plan, and anything you had to mark BLOCKED
+on season state so the user knows what the run won't cover.