fplkit 2.7.3__tar.gz → 2.8.0__tar.gz

fplkit-2.8.0/.agents/README.md

@@ -0,0 +1,51 @@
+# .agents/
+
+Agent skills for fpl-cli. Each subdirectory in `skills/` is a self-contained skill with a `SKILL.md` entry point.
+
+## Discovery
+
+Claude Code discovers skills via the `.claude/skills/` symlink, which points here. Other agent tools can read `skills/` directly.
+
+For a complete inventory of CLI commands, analysis agents, and skills, see [TOOLS.md](TOOLS.md).
+
+## Adapting Skills
+
+Skills are showcase examples - they work out of the box but are designed to be customised:
+
+- `<!-- ADAPT: ... -->` comments mark sections you'll want to change for your setup
+- Output paths use `[YOUR_OUTPUT_DIR]` placeholders - replace with your preferred location
+- Script invocations use a `[YOUR_PYTHON]` placeholder - replace with the interpreter fpl-cli is installed on. Helper scripts import the `fpl_cli` package, which a standalone `fpl` on `PATH` (uv tool, pipx) does not provide; get it wrong and they exit 1 with a JSON error envelope naming the cause
+- Supplementary data sources (newsletters, external reports) are noted but not required
+- All CLI data gathering uses `--format json` for structured output
+
+## Model and effort
+
+The four product skills (gw-prep, squad-builder, update-gw-prep, preview-ingest) pin a model and an effort level in their `SKILL.md` frontmatter, and every `Agent tool parameters` block pins its own pair, so a run does not depend on whatever the session happened to be set to (issue #393). The skills carry the reasons and point here; this table is the one place the levels are written down outside the blocks themselves.
+
+| Where | Model | Effort | Why |
+|---|---|---|---|
+| gw-prep orchestrator | opus | high | Gathers the data and assembles the report; the frontmatter also sets the level the Phase C prompts are built at |
+| gw-prep C1 classic analysis | opus | high | Weighs transfers, hits, chips and captaincy against each other: the most trade-off-heavy step in the repo |
+| gw-prep C2 draft analysis | sonnet | medium | No budget, chips or captains; the call is waivers and the lineup |
+| squad-builder orchestrator and Phase D assembly | opus | high | Assembly enforces every cross-position constraint and settles the trade-offs the position agents only surface |
+| squad-builder Phase C position research | opus | medium | Gathering and ranking within one position; the trade-offs are made in Phase D |
+| update-gw-prep orchestrator and sub-agent | opus | high | Revises the classic and draft recommendations against new information, so it inherits the classic analysis's trade-offs |
+| preview-ingest orchestrator and per-team agents | opus | medium | Extraction against a fixed schema: reading, not weighing |
+
+These levels are a judgement, not a measurement. `max` is untested here and probably not worth its time and cost; a gameweek of gw-prep run twice, once at these levels and once with classic at `max`, is the experiment that would settle it. Change a level in the block and in its row together: `tests/test_skill_effort_levels.py` reads each skill's frontmatter and every `Agent tool parameters` block, and holds each row of this table to the block its Where cell names (`orchestrator` is the frontmatter; the other labels are the sub-agent blocks in document order), so a swapped, missing or misspelt row fails there rather than being dropped.
+
+How far each key reaches, quoted from the Claude Code docs as read on 14 October 2026:
+
+- `model` in the frontmatter ([skills, Frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference)): "The override applies for the rest of the current turn and isn't saved to settings. The session model resumes when you send your next prompt." So a follow-up question about the output ("why sell X?") is answered on the session model.
+- `effort` in the frontmatter (same table): "Effort level when this skill is active. Overrides the session effort level." The docs do not say whether it reverts when the skill finishes.
+- `effort` in an `Agent tool parameters` block is the per-invocation parameter ([sub-agents, Choose an effort level](https://code.claude.com/docs/en/sub-agents#choose-an-effort-level)): "When you ask Claude to run a non-fork subagent at a specific effort level, it can also pass an `effort` parameter for that invocation. The parameter overrides the `effort` field and stays in effect when the subagent is resumed. The `CLAUDE_CODE_EFFORT_LEVEL` environment variable takes precedence over both. The per-invocation parameter requires Claude Code v2.1.292 or later."
+- claude.ai skill uploads and the Skills API ([skills, Using skill frontmatter outside Claude Code](https://code.claude.com/docs/en/skills#using-skill-frontmatter-outside-claude-code)) accept only the Agent Skills spec keys, `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`, and fail on anything else. `model` already fell outside that set, so `effort` adds no new break; strip both before uploading.
+- Codex, Cursor and Copilot (named in each skill's `compatibility` block) read neither key, so they run at whatever their session is set to.
+
+## Private Skills
+
+To add a private skill that shouldn't be committed, create it under `skills/` and add the path to `.gitignore`:
+
+```
+.agents/skills/my-private-skill/
+```

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/TOOLS.md

@@ -39,15 +39,15 @@ with `2>/dev/null` without losing the table, whichever command it runs.
 | `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. Classic positions are competition-ranked from cumulative totals — managers level on points share a place and the next distinct total skips the places they consumed — matching `fpl review` and the league history ledger rather than the standings API's sequential rank, which splits such a tie on fewest transfers season-to-date, a figure no column shows. Draft keeps the league's own rank, which already applies the head-to-head points-for tie-break | No | General | No | direct-api |
+| `league` | Show live league standings for Classic and Draft leagues. Classic positions are competition-ranked from cumulative totals — managers level on points share a place and the next distinct total skips the places they consumed — matching `fpl review` and the league history ledger rather than the standings API's sequential rank, which splits such a tie on fewest transfers season-to-date, a figure no column shows. Draft keeps the league's own rank, which already applies the head-to-head points-for tie-break. The Best/Worst GW Performers lists (top three; bottom five classic, bottom three draft) are the ones `fpl review` prints: managers level on the gameweek share a place (`3=`) and a tie at the cut keeps every manager in it, a hit reads `29 net pts (33 gross, -4 hit)`, and a classic user above the bottom five gets a `Your GW rank: R of N` line beside the list | 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. 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. 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. 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`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). 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 last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), 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. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover two checks on either format (issue #359): a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`), and a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold (`synthesis_unsupported_tie`). The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. 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. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. 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 |
+| `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 and grades the captain, each transfer and each waiver or free-agent move against it; the captain line sets the recommended captain against the armband in captain points (raw score times that week's multiplier, Triple Captain included), the armband being the vice's when the captain played no minutes, and adds the change to the team total when the recommended captain was in the side that scored; one who was not in the squad or played no minutes is labelled so rather than priced at 0; on a wildcard or free hit week, where the recommendation is a squad, each player brought in is graded against the recommended 15 instead, and a recommended name that fits more than one player is left ungraded with a warning on stderr rather than matched to the first; a part of the file it could not read (the captain, the transfers or the waivers) is left ungraded the same way, the warning naming the file, rather than grading every move unadvised, and a file nothing could be read from is not compared at all. 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 cut off at its token ceiling is retried once, told what the last draft lacked (a refused answer is flagged but never retried, and a retry that errors keeps the first attempt), 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`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). 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 last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), 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. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover two checks on either format (issue #359): a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`), and a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold (`synthesis_unsupported_tie`); and a third on draft (issue #390): the net overall, or the other kind's figure, said of one kind of a manager's moves ("his waiver moves netted +3 overall" of a -1 waiver and a +4 free-agent pickup, `synthesis_kind_net_misattribution`), for which a roster line that mixes kinds now gives each kind's net beside the net overall. The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. 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. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. 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 cut off at its token ceiling is regenerated once, told it was cut off (a refused editorial is never regenerated, even with a wrong claim in it), and one the provider stopped early on that is still the one kept is written out as it stands with the reason on stderr, a `synthesis_stopped_early` warning in JSON, and a line in the report's warning callout above the editorial (issue #372). 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 — including one `league-recap` appended against a manager who tied for last and was left out at capture. 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. 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 |
@@ -83,7 +83,7 @@ with `2>/dev/null` without losing the table, whichever command it runs.
 
 ## Skills
 
-Agent playbooks in `.agents/skills/`. Each has a `SKILL.md` entry point. Claude Code discovers them via the `.claude/skills/` symlink.
+Agent playbooks in `.agents/skills/`. Each has a `SKILL.md` entry point. Claude Code discovers them via the `.claude/skills/` symlink. The four product skills (gw-prep, squad-builder, update-gw-prep, preview-ingest) pin a model and an effort level in their frontmatter and in every sub-agent parameter block; the levels and the reasons for them are in [README.md](README.md#model-and-effort).
 
 Skills write their own outputs (`gw{N}-recommendations.md`, `gw{N}-squad-builder.md`, `season-start-squad.md`) into the same `<output dir>/<season>/` directory, for the same reason.
 
@@ -130,4 +130,4 @@ Python classes in `fpl_cli/agents/` that implement `async run(context) -> AgentR
 - `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 — 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.
+- 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. Both scripts read the tables inside those sections with `iter_tables`, the reader `fpl review --compare-recs` uses, so a `| - | - |` placeholder row never ends a table early. The waiver validator also cleans its cells with `split_name_team`, so a `(LIV, MID)` suffix comes off a name as `(LIV)` does, skips the same placeholder cells as the review (`No claim`, `-`), and reports rows under Waiver Recommendations that no table took in (`waiver-rows-unread`, via `pipe_rows`) rather than passing them unchecked. It still matches the template's column names exactly, where the review takes aliases: it checks gw-prep's fresh output, not older files.

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/gw-prep/SKILL.md

@@ -6,6 +6,7 @@ description: >
   each league format. Use when the user asks to prepare for the next gameweek,
   get transfer/waiver recommendations, or review their squad.
 model: opus
+effort: high
 compatibility:
   claude-code: full (parallel Classic + Draft sub-agents via Agent tool)
   codex: partial (sequential execution - no sub-agent spawning)
@@ -38,6 +39,8 @@ Get it wrong and the scripts say so: each one exits 1 with `{"error": true, "mes
 
 **In all cases** the final output format is identical: Classic section followed by Draft section (or whichever formats are active).
 
+**Model and effort:** the frontmatter pins the orchestrator's model and effort, and each Phase C block pins its own pair. Classic gets more effort than draft because it weighs transfers, hits, chips and captaincy against each other, while draft has no budget, chips or captains to trade off. These are judgement calls, not measurements; the levels, the reasoning and how far each override reaches are in `.agents/README.md` (Model and effort).
+
 ---
 
 ## Phase A: Context Detection
@@ -358,8 +361,13 @@ Each sub-agent receives the JSON output from Phase B commands as context.
 
 ### C1 -- Classic League Analysis (skip if format is "draft")
 
-- **model**: opus
-- **subagent_type**: general-purpose
+```
+Agent tool parameters:
+  subagent_type: general-purpose
+  model: opus
+  effort: high
+  description: "GW prep - classic analysis"
+```
 
 Branch on `squad_builder_result` (set in Phase A3; unset on transfer weeks):
 
@@ -589,8 +597,13 @@ Proceed immediately (non-interactive).
 
 ### C2 -- Draft League Analysis (skip if format is "classic")
 
-- **model**: sonnet
-- **subagent_type**: general-purpose
+```
+Agent tool parameters:
+  subagent_type: general-purpose
+  model: sonnet
+  effort: medium
+  description: "GW prep - draft analysis"
+```
 
 **Prompt structure:**
 
@@ -770,6 +783,10 @@ _Runs after Phase D file write, before Phase E. Not embed-gated._
      > Edit the file to fix the flagged row(s), then re-run `/gw-prep` to continue.
      
      **Stop the pipeline.** Do not proceed to Phase E. Do not mark the run as complete.
+   - Else, if a warning has `type == "waiver-rows-unread"` → emit this in-chat warning, followed by the pool-miss one below if any `waiver-not-in-pool` flags are present too:
+     > ⚠️ Phase D1: {rows} row(s) under Waiver Recommendations in `gw{N}-recommendations.md` were not read as waiver rows, so they were not checked for cross-position swaps. A table needs a `|---|` row straight under its header, no blank line inside it, and nothing stacked beneath it. Fix the table and re-run `/gw-prep` before submitting waivers.
+
+     Proceed to Phase E.
    - Else (only warnings and/or `waiver-not-in-pool` flags) → emit an in-chat warning:
      > ⚠️ Phase D1: {N} waiver pool miss(es) in `gw{N}-recommendations.md` — see managed block in the Draft section. Claims may be normaliser false positives; verify before submitting waivers.
      

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/gw-prep/references/output-template.md

@@ -195,6 +195,8 @@ The **Data quality** sub-section carries `data_caveat` from gw-prep Phase B1 --
 
 Every recommendation in this file that leans on fixture difficulty rests on those ratings, so this belongs with the recommendations rather than only in the terminal scrollback the run scrolled past.
 
+**Read back by `fpl review --compare-recs`.** The review grades what was done against this file, through the column headers of Transfer Recommendations (`Out`, `In`) and Waiver Recommendations (`Drop`, `Claim`), the `**Recommended captain:**` line, and on embed-mode runs the Classic Squad's `#### Starting XI` and `#### Bench` tables. Write them exactly as above, with the club code in brackets after each player (`Tzolis (ARS)`) and the initial left on (`B.Fernandes`, not `Fernandes`): a renamed column leaves every move in that table ungraded, and a bare surname cannot be told apart from a same-club namesake. When there is nothing to recommend, say so in words ("Roll the free transfer", "No waiver claims this week") rather than leaving the table's rows blank: a blank table reads the same as one the review could not parse. `tests/test_recommendations_parser.py` parses this template, so change it and `fpl_cli/parsers/recommendations.py` together.
+
 ---
 
 ## Fallback Banners (Wildcard/Free Hit re-derivation)

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/gw-prep/scripts/extract_classic_squad.py

@@ -31,6 +31,7 @@ from fpl_cli.utils.markdown import (
     fence_flags,
     find_section,
     has_heading,
+    iter_tables,
     leaf_body,
     parse_heading,
 )
@@ -325,9 +326,6 @@ def _validate_classic_squad_block(block: str) -> ValidationResult:
     }
 
 
-_TABLE_SEPARATOR_RE = re.compile(r"^\|[-:| ]+\|")
-
-
 def _lines_in_section(block: str, heading: str | HeadingMatcher) -> list[str]:
     """Return the body lines of `heading`'s section within `block`.
 
@@ -340,21 +338,7 @@ def _lines_in_section(block: str, heading: str | HeadingMatcher) -> list[str]:
 
 def _count_table_rows_between(block: str, start_heading: str | HeadingMatcher) -> int:
     """Count markdown table data rows between start_heading and the next heading of same depth."""
-    in_table = False
-    row_count = 0
-
-    for line in _lines_in_section(block, start_heading):
-        if line.startswith("|"):
-            if _TABLE_SEPARATOR_RE.match(line):
-                pass
-            elif not in_table:
-                in_table = True
-            else:
-                row_count += 1
-        elif in_table:
-            in_table = False
-
-    return row_count
+    return sum(len(table.rows) for table in iter_tables(_lines_in_section(block, start_heading)))
 
 
 def _parse_budget_total(block: str) -> float | None:
@@ -376,26 +360,13 @@ def _tally_teams_from_squad_tables(block: str) -> dict[str, int]:
     """Tally team counts from the Team column in Starting XI and Bench tables."""
     tally: dict[str, int] = {}
     for section_heading in (_HEADING_STARTING_XI, _HEADING_BENCH):
-        in_table = False
-        team_col: int | None = None
-        for line in _lines_in_section(block, section_heading):
-            if line.startswith("|"):
-                if _TABLE_SEPARATOR_RE.match(line):
-                    pass  # separator
-                elif not in_table:
-                    headers = [h.strip().lower() for h in line.strip("|").split("|")]
-                    team_col = next(
-                        (i for i, h in enumerate(headers) if h == "team"), None
-                    )
-                    in_table = True
-                else:
-                    if team_col is not None:
-                        parts = [p.strip() for p in line.strip("|").split("|")]
-                        if len(parts) > team_col and parts[team_col]:
-                            team = parts[team_col]
-                            tally[team] = tally.get(team, 0) + 1
-            elif in_table:
-                in_table = False
+        for table in iter_tables(_lines_in_section(block, section_heading)):
+            team_col = next((i for i, h in enumerate(table.headers) if h.lower() == "team"), None)
+            if team_col is None:
+                continue
+            for row in table.rows:
+                if team_col < len(row) and row[team_col]:
+                    tally[row[team_col]] = tally.get(row[team_col], 0) + 1
     return tally
 
 
@@ -407,18 +378,17 @@ def _parse_team_exposure(block: str) -> dict[str, int]:
     """
     exposure: dict[str, int] = {}
 
-    for line in _lines_in_section(block, _HEADING_TEAM_EXPOSURE):
-        if line.startswith("|") and not _TABLE_SEPARATOR_RE.match(line):
-            parts = [p.strip() for p in line.strip("|").split("|")]
-            if len(parts) >= 2:
-                team = parts[0].strip()
-                try:
-                    count = int(parts[1].strip().strip("*"))
-                    team_clean = team.strip("*").strip()
-                    if team_clean and team_clean.lower() not in ("team", "total"):
-                        exposure[team_clean] = count
-                except ValueError:
-                    pass
+    for table in iter_tables(_lines_in_section(block, _HEADING_TEAM_EXPOSURE)):
+        for row in table.rows:
+            if len(row) < 2:
+                continue
+            team = row[0].strip("*").strip()
+            try:
+                count = int(row[1].strip("*"))
+            except ValueError:
+                continue
+            if team and team.lower() != "total":
+                exposure[team] = count
 
     if not exposure:
         return _tally_teams_from_squad_tables(block)

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/gw-prep/scripts/validate_draft_waivers.py

@@ -35,7 +35,16 @@ from typing import NotRequired, TypedDict, cast
 # envelope instead of a ModuleNotFoundError traceback.
 import _bootstrap  # noqa: F401 — import guard, see module docstring
 
-from fpl_cli.utils.markdown import HeadingMatcher, find_section, leaf_body
+from fpl_cli.parsers.recommendations import PLACEHOLDER_CELLS
+from fpl_cli.utils.markdown import (
+    HeadingMatcher,
+    find_section,
+    has_heading,
+    iter_tables,
+    leaf_body,
+    pipe_rows,
+    split_name_team,
+)
 
 # ---------------------------------------------------------------------------
 # Types
@@ -54,6 +63,7 @@ class Flag(TypedDict, total=False):
 class Warning(TypedDict, total=False):
     type: str
     name: str
+    rows: int
 
 
 class ValidatorResult(TypedDict):
@@ -81,18 +91,14 @@ class SquadEntry(TypedDict):
 
 _APOSTROPHE_RE = re.compile(r"[‘’ʼʹ`]")
 _HYPHEN_RE = re.compile(r"[–—‒‐‑]")
-_TEAM_SUFFIX_RE = re.compile(r"\s*\([A-Z]{2,4}\)\s*$")
-_MARKDOWN_WRAP_RE = re.compile(r"^[\*_`]+|[\*_`]+$")
 _WHITESPACE_RE = re.compile(r"\s+")
 
 
 def normalise(name: str) -> str:
     """Return a canonical key for name matching."""
-    s = name.strip()
-    # strip markdown bold/italic/code wrapping
-    s = _MARKDOWN_WRAP_RE.sub("", s).strip()
-    # strip trailing team suffix like "(CHE)" or "(TOT)"
-    s = _TEAM_SUFFIX_RE.sub("", s).strip()
+    # strip markdown wrapping and every trailing bracket: "(CHE)", "(LIV, MID)",
+    # "(if fit)" -- the same cell cleaning `fpl review --compare-recs` reads with
+    s, _ = split_name_team(name)
     # NFKD decompose then drop combining marks
     s = unicodedata.normalize("NFKD", s)
     s = "".join(c for c in s if not unicodedata.category(c).startswith("M"))
@@ -109,12 +115,12 @@ def normalise(name: str) -> str:
     return s
 
 
-_PLACEHOLDER_VALUES = frozenset({"-", "—", "–", "", "hold", "(depth)", "tbd", "n/a"})
-
-
 def _is_placeholder(raw: str) -> bool:
-    key = normalise(raw)
-    return key in _PLACEHOLDER_VALUES or (key.startswith("(") and key.endswith(")"))
+    """A cell standing in for "no move here", by the cells `fpl review
+    --compare-recs` skips: "-", "hold", "No claim". A cell that is nothing but
+    a bracket ("(depth)") normalises to "", since normalise takes every
+    trailing bracket off a name."""
+    return normalise(raw) in PLACEHOLDER_CELLS
 
 
 # ---------------------------------------------------------------------------
@@ -245,44 +251,19 @@ def parse_waiver_table(
     """Parse the first markdown table in the section.
 
     Returns (headers, rows) where rows are dicts keyed by header name,
-    or None if no table found.
+    or None if no table found. The table is read by the same rules as
+    `fpl review --compare-recs` reads it (`iter_tables`): a placeholder row
+    of bare dashes is skipped rather than ending the table above it, and a
+    table stacked straight under this one is its own table, not more rows.
     """
-    headers: list[str] | None = None
-    rows: list[dict[str, str]] = []
-
-    lines_iter = list(section_lines)
-    for idx, line in enumerate(lines_iter):
-        stripped = line.strip()
-        if not stripped.startswith("|"):
-            # End table at first non-pipe line after rows started (e.g. blank line
-            # before the next ### subsection's table).
-            if rows:
-                break
-            continue
-        if headers is None:
-            # first pipe-delimited line is the header row
-            parts = [p.strip() for p in stripped.strip("|").split("|")]
-            headers = parts
-            continue
-        # skip separator row
-        if re.match(r"^\|[-| ]+\|", stripped):
-            continue
-        # Detect a new header row stacked directly after the current table:
-        # current line is pipe-delimited and the next line is a separator. Break
-        # before consuming it as a data row.
-        if rows and idx + 1 < len(lines_iter):
-            next_stripped = lines_iter[idx + 1].strip()
-            if re.match(r"^\|[-| ]+\|", next_stripped):
-                break
-        parts = [p.strip() for p in stripped.strip("|").split("|")]
-        row: dict[str, str] = {}
-        for i, h in enumerate(headers):
-            row[h] = parts[i] if i < len(parts) else ""
-        rows.append(row)
-
-    if headers is None:
+    table = next(iter_tables(section_lines), None)
+    if table is None:
         return None
-    return headers, rows
+    rows = [
+        {header: row[i] if i < len(row) else "" for i, header in enumerate(table.headers)}
+        for row in table.rows
+    ]
+    return table.headers, rows
 
 
 # ---------------------------------------------------------------------------
@@ -449,12 +430,29 @@ def _run(recommendations_file: str, waivers_json: str, squad_grid_json: str) ->
 
     # Parse waiver table
     table = parse_waiver_table(waiver_lines)
+
+    # Rows under the heading that the waiver table did not take in -- a header
+    # with no `|---|` row under it, rows a blank line cut off, a table stacked
+    # beneath -- were never checked, so say so rather than pass a clean result.
+    # Only under the heading itself: the whole-section fallback holds the
+    # Starting XI and Bench tables too.
+    unread = 0
+    if has_heading(section_lines, _HEADING_WAIVERS):
+        read = 0 if table is None else 1 + len(table[1])
+        unread = len(pipe_rows(waiver_lines)) - read
+    if unread > 0:
+        warnings.append(Warning(type="waiver-rows-unread", rows=unread))
+
     if table is None:
-        warnings.append(Warning(type="waiver-table-not-found"))
+        if unread <= 0:
+            warnings.append(Warning(type="waiver-table-not-found"))
         result = {"ok": True, "flags": [], "warnings": warnings}
         json.dump(result, sys.stdout)
         return
 
+    # Exact column names, where `fpl review --compare-recs` takes aliases and
+    # any case: it also reads older and post-waiver files under other headers,
+    # while this checks gw-prep's own fresh output, written to the template's.
     headers, rows = table
     if "Drop" not in headers or "Claim" not in headers:
         warnings.append(Warning(type="drop-claim-columns-not-found"))

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/preview-ingest/SKILL.md

@@ -7,6 +7,7 @@ description: >
   "build my previews folder", or hands over a team preview article and wants it
   usable by squad-builder and gw-prep.
 model: opus
+effort: medium
 compatibility:
   claude-code: full (parallel per-team ingestion via Agent tool)
   codex: full (single sequential pass)
@@ -54,6 +55,16 @@ expires on a schedule the loader already knows (`fpl intel --show-decay`).
 team in a single parallel Agent tool block, each running Phases B–D for its own
 team. They write to different files and do not interact.
 
+```
+Agent tool parameters (per agent):
+  subagent_type: general-purpose
+  model: opus
+  effort: medium
+  description: "Preview ingest - {TEAM}"
+```
+
+**Model and effort:** the frontmatter pins the orchestrator's model and effort and the block above pins each per-team agent's, both at the effort of an extraction step rather than a trade-off step: the schema fixes what to look for, so the work is finding it in the prose, not weighing options. A judgement call, not a measurement; the levels, the reasoning and how far each override reaches are in `.agents/README.md` (Model and effort).
+
 **Other agents:** run Phases B–D sequentially per team.
 
 ## Phase B: Extract

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/squad-builder/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: squad-builder
 model: opus
+effort: high
 description: >-
   Build an optimal 15-player FPL squad from scratch. Handles mid-season wildcard,
   free hit, and season-start squad selection for both Classic and Draft formats.
@@ -31,6 +32,8 @@ Build-from-scratch squad optimisation. Five modes, one pipeline.
 
 **Codex / Cursor / Copilot / other agents:** Run all phases sequentially in the same context. Phase B commands can be parallelised if the tool supports it. Phase B2 shortlisting and Phase C position research can be done inline per position. Use the Phase D assembly prompt as a direct instruction rather than dispatching a sub-agent.
 
+**Model and effort:** the frontmatter pins the orchestrator's model and effort, and the Phase C and Phase D blocks pin their own. Assembly gets more effort than position research because it enforces every cross-position constraint and settles the trade-offs the position agents only surface, whereas research gathers and ranks within one position. These are judgement calls, not measurements; the levels, the reasoning and how far each override reaches are in `.agents/README.md` (Model and effort).
+
 ---
 
 ## Phase A: Context Detection
@@ -250,6 +253,7 @@ Launch 4 position-research agents in a **single parallel Agent tool block**:
 Agent tool parameters (per agent):
   subagent_type: general-purpose
   model: opus
+  effort: medium
   description: "Squad builder - {POSITION} research"
 ```
 
@@ -377,6 +381,7 @@ Launch after all Phase C agents return (or fail with fallback):
 Agent tool parameters:
   subagent_type: general-purpose
   model: opus
+  effort: high
   description: "Squad builder - {mode} assembly"
 ```
 

{fplkit-2.7.3 → fplkit-2.8.0}/.agents/skills/update-gw-prep/SKILL.md

@@ -7,6 +7,7 @@ description: >
   file. Use when the user says "update gw prep", "second pass", "add gw
   update", or wants to revise recommendations with new information.
 model: opus
+effort: high
 compatibility:
   claude-code: full (single sub-agent via Agent tool)
   codex: full (single sequential pass)
@@ -110,6 +111,18 @@ Read the scoring and formatting rules:
 
 Dispatch a single sub-agent with the following brief.
 
+```
+Agent tool parameters:
+  subagent_type: general-purpose
+  model: opus
+  effort: high
+  description: "Update GW prep - gameweek {N}"
+```
+
+**Model and effort:** the frontmatter pins the orchestrator's model and effort and the block above pins the sub-agent's, both at the effort of a trade-off step rather than an extraction step: the update revises the classic and draft recommendations against new information, so it inherits the classic analysis's trade-offs (transfers, hits, chips, captaincy). A judgement call, not a measurement; the levels, the reasoning and how far each override reaches are in `.agents/README.md` (Model and effort).
+
+**Other agents:** apply the brief inline in the same context.
+
 #### Sub-agent brief
 
 You are updating gameweek recommendations with new information. Your job is to

{fplkit-2.7.3 → fplkit-2.8.0}/AGENTS.md

@@ -36,7 +36,7 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 - Help text: describe what the user sees, never reference internal components ("agent", "client")
 - Inner async function: always name `_run`
 - `--format json` commands emit the shared envelope via `emit_json()` / `emit_json_error()` (`cli/_json.py`), never a bare `json.dumps`. Both envelopes go to stdout and every human-readable line to stderr — success is `{command, metadata, data}` and exit 0, failure is `{command, error}` and exit 1, so a consumer parses one stream either way
-- Table mode splits the same way: the table on stdout, and every other line — warnings, progress notices, and the reason for a nonzero exit — on stderr, so `2>/dev/null` means the same thing on every command. Report a failure with `emit_failure()` (or `handle_agent_failure()` for an agent's), and where a call site prints its own prose before `raise SystemExit(1)`, print it on `error_console`, never on `console`
+- Table mode splits the same way: the table on stdout, and every other line — warnings, progress notices, and the reason for a nonzero exit — on stderr, so `2>/dev/null` means the same thing on every command. Report a failure with `emit_failure()` (or `handle_agent_failure()` for an agent's), and where a call site prints its own prose before `raise SystemExit(1)`, print it on `error_console`, never on `console`. `tests/test_cli_notice_streams.py` enforces this on the `fpl review` modules by reading their source; add a module to its `SCANNED_MODULES` once its hits are triaged
 - A failure raised too deep to know the command name or the format goes through a boundary: `api_failure_boundary(command, output_format)` around the `asyncio.run()` for an unreachable upstream, and the `@config_failure_boundary` decorator on the command callback for a `settings.yaml` block a parser rejected. A config parser raises `ConfigError` (`cli/_context.py`) and nothing wider, so the boundary catches the defect and a bug in our own code still surfaces as a traceback — a bare `ValueError` escapes click and, under `--format json`, exits 1 with zero bytes on stdout (#170)
 - **Format awareness:** New commands classified in `CLASSIC_ONLY`/`DRAFT_ONLY` frozensets in `_context.py` (omit for General). Shared commands use `@click.pass_context` and `fmt = get_format(ctx)` to gate irrelevant sections (see `league.py` for pattern).
 - **Context access:** A command reads its settings with `get_settings(ctx)` and its format with `get_format(ctx)` — never by unwrapping `ctx.obj` and never by calling `load_settings()` a second time; `main()` already merged them onto the context. A ruff `TID251` rule enforces both, banning the `CLIContext` and `load_settings` imports in `fpl_cli/cli/` outside `__init__.py` and `doctor.py`. `load_settings()` is for callers with no context (agents, services) and for `fpl doctor`, which runs on an empty `CLIContext` so each check re-reads by design. A helper too deep to hold a context takes the value it needs as an argument (see `transfer_eval.py`'s `_render_table`)

{fplkit-2.7.3 → fplkit-2.8.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [2.7.4] - 2026-10-09
+
+### Bug Fixes
+
+- league-recap checks no longer misread part of one name as another (#380)
+- fpl league's best/worst GW performers now match fpl review (#385)
+- fpl review sends its notices to stderr instead of stdout (#386)
+
+## [2.7.3] - 2026-10-09
+
+### Bug Fixes
+
+- default synthesis model moves to claude-sonnet-5-5 (#362)
+- stop streak notes calling a fully recorded gameweek "not recorded" (#363)
+- show correct ranks and scores in the gameweek review report (#365)
+- review no longer drops the transfers summary on a net-zero total (#366)
+- draft review no longer misreports rendering errors as a failed fetch (#369)
+- stop gw-prep, squad-builder and FPL Mate ruling out a legal 5-2-3 (#370)
+- flag a recap editorial that misnames who lost a contested waiver (#368)
+- draft review no longer crashes on bracketed player or manager names (#373)
+- classic review no longer crashes on bracketed names (#378)
+- flag recap editorials that misplace a transfer net or invent a tie (#374)
+
 ## [2.7.2] - 2026-09-16
 
 ### Bug Fixes