fplkit 1.2.0__tar.gz → 1.2.1__tar.gz

{fplkit-1.2.0 → fplkit-1.2.1}/.agents/skills/squad-builder/SKILL.md

@@ -244,7 +244,7 @@ Include all of this in the prompt field, populated with position-specific data:
    Run `fpl player "{name}" -f -H` **in parallel** for all candidates in your list.
    For season-start modes with no current-season data, also use `fpl history` data passed in context.
 
-7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use quality_score and quality_per_m when available (null for players without Understat data - don't penalise).
+7. **Scoring:** Score each candidate against the mode-specific criteria from rules. Use `quality_score` and `quality_per_m` when available (null for players without Understat data — don't penalise). **Both fields are elite-within-position: never rank or compare candidates across positions by `quality_score` or `quality_per_m`.** A DEF showing 85 and a MID showing 55 is not "the DEF is better" — the ceilings differ by design. Only compare within the position you are currently filling.
 
 8. **Return format:** Return a structured ranked list. Per candidate:
    ```

{fplkit-1.2.0 → fplkit-1.2.1}/.agents/skills/squad-builder/references/rules.md

@@ -32,7 +32,7 @@ After building, note how many of the user's current players (if known) appear in
 
 ## Value-for-Money
 Available in `fpl player --format json` output when Understat data exists for the player:
-- **quality_score** (0-100): Player output quality normalised against positional ceiling. Form and PPG weighted heavily - measures "current FPL points production rate."
+- **quality_score** (0-100): Player output quality normalised against a **position-specific** ceiling. Treat as an **elite-within-position** index: a GK or DEF scoring 90 is "top of their position", not "better than an 85-rated MID/FWD". Raw quality is attenuated by a position multiplier (GK 0.7, DEF 0.85) and DEF/GK use dedicated signal sets (`without_xgi()` / `for_gk()`), so cross-position comparisons of `quality_score` are not meaningful. Form and PPG weighted heavily.
 - **quality_per_m** (quality_score / price per GBPm): Within-position budget efficiency. Higher = more output per pound.
 - When choosing between similarly-ranked candidates at the same position, prefer higher `quality_per_m` to free budget for other slots.
 - `quality_per_m` is not meaningful for cross-position comparison (positional ceilings differ).

{fplkit-1.2.0 → fplkit-1.2.1}/.gitignore

@@ -87,8 +87,7 @@ todos/
 .agents/skills/documentation-writer/
 .agents/skills/release-notes/
 .agents/skills/release/
-.agents/skills/senior-data-scientist/
-.agents/skills/data-scientist/
 .agents/skills/fpl-data-scientist/
+
 # OS
 .DS_Store

{fplkit-1.2.0 → fplkit-1.2.1}/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [1.2.0] - 2026-04-09
+
+### Bug Fixes
+
+- gate xGI sustainability behind custom_analysis flag
+- attenuate GK signals for low-minutes keepers
+
+### Features
+
+- add player reliability metric (#10)
+- add rolling-window xGI sustainability signal (#11)
+- add GK-specific quality scoring path (#12)
+- fixture-adjusted npxG to remove double-counting (#13)
+- add consistency index signals (Phase 1) (#14)
+- wire consistency signals into scoring (Phase 2) (#15)
+
 ## [1.1.0] - 2026-04-07
 
 ### Bug Fixes

{fplkit-1.2.0 → fplkit-1.2.1}/CLAUDE.md

@@ -21,7 +21,7 @@ API clients in `fpl_cli/api/`: FPLClient (main API, caches `bootstrap-static/`),
 - `Player`: `element_type` = position, `team` = team_id, `code` = stable cross-season ID (element_code). Prices in £0.1m units (100 = £10.0m)
 - `Fixture`: `gameweek` (alias "event"), `home_team_id`/`away_team_id`
 
-For a complete inventory of CLI commands, analysis agents, and skills with JSON support and format awareness, see `.agents/TOOLS.md`.
+For a complete inventory of CLI commands, analysis agents, and skills with JSON support and format awareness, see `.agents/TOOLS.md`. Skills live in `.agents/skills/`.
 
 ## Conventions
 ### CLI Patterns

{fplkit-1.2.0 → fplkit-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fplkit
-Version: 1.2.0
+Version: 1.2.1
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli
@@ -38,7 +38,7 @@ Fantasy Premier League analysis from the terminal. Classic and Draft formats. Si
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-<img src="docs/images/fpl-player-demo-v1-0.png"
+<img src="https://raw.githubusercontent.com/rossgroomio/fpl-cli/main/docs/images/fpl-player-demo-v1-0.png"
      alt="FPL player scouting table in fpl-cli showing form, xGI, expected goals, availability flags and Fantasy Premier League data"
      width="600"
      style="max-width: 100%; height: auto;">

{fplkit-1.2.0 → fplkit-1.2.1}/README.md

@@ -6,7 +6,7 @@ Fantasy Premier League analysis from the terminal. Classic and Draft formats. Si
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-<img src="docs/images/fpl-player-demo-v1-0.png"
+<img src="https://raw.githubusercontent.com/rossgroomio/fpl-cli/main/docs/images/fpl-player-demo-v1-0.png"
      alt="FPL player scouting table in fpl-cli showing form, xGI, expected goals, availability flags and Fantasy Premier League data"
      width="600"
      style="max-width: 100%; height: auto;">

{fplkit-1.2.0 → fplkit-1.2.1}/docs/command-reference.md

@@ -75,7 +75,7 @@ Groups players into tiers:
 - **Popular** (15-30% owned): Emerging picks
 - **Differential** (<15% owned): Low-ownership value
 
-Target score combines xG metrics, form, PPG, 3-GW matchup quality, and consistency (CV-xGI percentile bonus, phased in GW6-10), normalised to 0-100. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Target Score](custom-analysis.md#target-score) for the full formula.
+Target score combines xG metrics, form, PPG, 3-GW matchup quality, and consistency (CV-xGI percentile bonus, phased in GW6-10), attenuated by position multiplier (GK 0.7, DEF 0.85), and normalised to 0-100. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Target Score](custom-analysis.md#target-score) for the full formula.
 
 ### Transfer Evaluation
 
@@ -99,7 +99,7 @@ Output columns:
 - **Form** - FPL form (last 30 days PPG)
 - **Status** - availability indicator
 - **Avail** - historical availability rate (recency-weighted starts across previous seasons). Null when no historical data.
-- **Quality** - price-independent player quality (0-100). Uses `VALUE_QUALITY_WEIGHTS`. Null when no Understat match.
+- **Quality** - price-independent player quality (0-100), normalised against a position-specific ceiling. Elite-within-position index — cross-position comparisons not meaningful (GK/DEF/MID/FWD use different ceilings by design). See [Quality & Value Scores](custom-analysis.md#quality--value-scores). Null when no Understat match.
 - **Value** - quality per GBP million (`quality_score / price`). Higher = more output per pound. Null when no Understat match or price is 0. *(classic only)*
 - **Price** - current price *(classic only)*
 - **Budget** - affordability gap: `bank + sell_price - in_price` *(classic only, requires scraper cache)*
@@ -121,7 +121,7 @@ fpl differentials -m 200     # Require 200+ minutes played
 fpl differentials --format json  # JSON envelope (metadata: {gameweek})
 ```
 
-Differential score combines xG metrics, form, ownership bonus, 3-GW matchup quality, and consistency (inverted CV-xGI bonus - volatile players score higher, phased in GW6-10), normalised to 0-100. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Differential Score](custom-analysis.md#differential-score) for the full formula.
+Differential score combines xG metrics, form, ownership bonus, 3-GW matchup quality, and consistency (inverted CV-xGI bonus - volatile players score higher, phased in GW6-10), attenuated by position multiplier (GK 0.7, DEF 0.85), and normalised to 0-100. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Differential Score](custom-analysis.md#differential-score) for the full formula.
 
 ### Waiver Recommendations
 
@@ -134,7 +134,7 @@ fpl waivers --format json
 
 Identifies squad weaknesses by position, ranks available free agents by waiver score, suggests who to drop for each pickup. This covers the waiver wire (unclaimed players) only - trade recommendations between managers are not in scope.
 
-Waiver score combines xGI, form, PPG, 3-GW matchup quality, and consistency (CV-xGI percentile bonus, phased in GW6-10), normalised to 0-100. Uses a stricter minutes factor than target/differential because draft waivers are a season commitment. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Waiver Score](custom-analysis.md#waiver-score) for the full formula.
+Waiver score combines xGI, form, PPG, 3-GW matchup quality, and consistency (CV-xGI percentile bonus, phased in GW6-10), attenuated by position multiplier (GK 0.7, DEF 0.85), and normalised to 0-100. Uses a stricter minutes factor than target/differential because draft waivers are a season commitment. Subject to [early-season shrinkage](custom-analysis.md#early-season-confidence-gw1-10). See [Waiver Score](custom-analysis.md#waiver-score) for the full formula.
 
 ## Fixture & Strategic Planning
 
@@ -169,6 +169,8 @@ Scores ~500 eligible players, adjusts for fixture difficulty over the planning h
 
 **JSON output fields:** `id`, `web_name`, `team`, `position`, `price`, `quality_score` (0-100), `raw_quality` (float), `role` (starter/bench), `captain_gws`. Metadata includes `formation`, `budget_used`, `budget_remaining`, `captain_schedule`, `solver_status`.
 
+**`quality_score` semantics:** At `--horizon >= 2` each player's `quality_score` is normalised against a position-specific VALUE-family ceiling (matching `fpl player` / `fpl stats --value` / `fpl transfer-eval`), so elite GKs, DEFs, MIDs and FWDs all land in comparable 0-100 bands *within their own position*. At `--horizon 1` a single cross-position `STARTING_XI_CEILING` is used — a deliberate asymmetry retained until the single-GW lineup ceilings are split per position; at that horizon, DEFs and GKs display noticeably lower than MIDs/FWDs for the same real-world quality. Use `raw_quality` for a position-agnostic ranking in the single-GW context.
+
 ### Fixture Difficulty (FDR)
 
 Analyse upcoming fixture runs with difficulty ratings, blank/double GW detection, and optional squad exposure.
@@ -276,7 +278,7 @@ fpl stats --min-minutes 900 -s expected_goals        # Top xG (min 900 mins)
 fpl stats -p FWD -s form --available-only            # FWDs by form, excl. unavailable
 fpl stats --format json -p MID -s expected_goal_involvements  # JSON for agents
 fpl stats --value -p MID                             # MIDs ranked by value/£m
-fpl stats --value --sort quality_score -p FWD        # FWDs by absolute quality
+fpl stats --value --sort quality_score -p FWD        # FWDs ranked by within-position quality_score
 fpl stats --value --window 3 -p MID                  # Rolling pts/£m over last 3 qualifying GWs
 ```
 

{fplkit-1.2.0 → fplkit-1.2.1}/docs/custom-analysis.md

@@ -117,16 +117,19 @@ FDR is not an additive component in either scoring family.
 
 #### Position Multiplier
 
-Applies to **ceiling components only** (matchup + form + xGI), not to home/pen bonuses:
+Applies to the quality baseline in **both** scoring families:
+
+1. **Single-GW family** (captain, bench, lineup): multiplies ceiling components (matchup + form + xGI) inside `calculate_single_gw_core`. Home and penalty bonuses are not attenuated.
+2. **Multi-GW ownership family** (target, differential, waiver, value, allocate): multiplies the quality baseline inside `calculate_player_quality_score`. Matchup bonus, ownership bonus and position-need bonus are added un-attenuated on top.
 
 | Position | Multiplier | Rationale |
 |----------|-----------|-----------|
 | FWD | 1.0 | Highest explosive upside per game (49% drop-off from top-1 to top-10 season scores) |
 | MID | 1.0 | Similar ceiling to FWD via goals + clean sheet points |
-| DEF | 0.85 | Consistent accumulators (28% drop-off) but lower single-GW ceiling |
-| GK | 0.7 | Lowest per-game ceiling; value comes from steady accumulation |
+| DEF | 0.85 | Consistent accumulators (28% drop-off) but lower per-GW ceiling |
+| GK | 0.7 | Lowest per-GW ceiling; value comes from steady accumulation |
 
-This means a defender needs a meaningfully better matchup to out-rank a forward as captain. This is intentional: defenders accumulate well over a season (top-10 DEF avg 138 pts vs FWD 131) but captaincy is a single-GW decision where explosive upside matters more.
+The multi-GW path was added on 2026-04-10 to stop cheap GKs (Raya, Kelleher, Darlow) dominating `raw_quality` and forcing the allocator into 5-3-2 / GK-captain solutions. See `docs/plans/2026-04-10-001-fix-multi-gw-scoring-position-rebalance-plan.md` for the empirical rationale and the supersession of the dc-per-90-calibration decision.
 
 #### Normalisation
 
@@ -334,9 +337,12 @@ If Core-Insights data is unavailable, the pipeline falls back to raw npxG/90 wit
 
 Available via `fpl stats --value` and `fpl player` when Understat data exists.
 
-**quality_score** (0-100): Normalised player output quality using `VALUE_QUALITY_WEIGHTS`. Weights form and PPG heavily to capture current FPL points production rate. Position-specific scoring paths diverge for defensive players:
-- **GK**: dedicated signals via `for_gk()` weights — saves per 90, defensive quality (inverted xGC/90, range 0-2), and clean sheet rate. Normalised against `GK_VALUE_CEILING` (28.2).
-- **DEF**: `dc_per_90` (defensive contribution rate) replaces attacking xG stats via `without_xgi()`. Normalised against `VALUE_CEILING` (24.3).
+**quality_score** (0-100): Normalised player output quality using `VALUE_QUALITY_WEIGHTS`. Weights form and PPG heavily to capture current FPL points production rate. Position-specific scoring paths diverge for GK/DEF: raw scores are attenuated by `POSITION_SCORE_MULTIPLIER` before normalisation, **and the normalisation ceiling itself is derived empirically from the active signal set per position**, so `quality_score` is a clean **elite-within-position** index. Cross-position comparisons (e.g. "is Haaland more elite than Raya?") are not meaningful — the ceilings differ by design.
+- **GK**: dedicated signals via `for_gk()` weights — saves per 90, defensive quality (inverted xGC/90, range 0-2), and clean sheet rate. Raw quality attenuated by 0.7 and normalised against `GK_VALUE_CEILING` (~18.8), derived from the `for_gk()` cap sum × 0.7. The form cap uses trajectory-only headroom (`× 1.2`) because `xgi_sustainability` is always 1.0 for non-ATK positions.
+- **DEF**: `dc_per_90` (defensive contribution rate) replaces attacking xG stats via `without_xgi()`. Raw quality attenuated by 0.85 and normalised against `DEF_VALUE_CEILING` (~13.1), derived from the `without_xgi()` cap sum × 0.85 — **not** the MID/FWD-anchored `VALUE_CEILING`. Same trajectory-only form headroom as GK. This replaces a prior MID-anchored scaling that produced a mathematical no-op (both numerator and denominator scaled by 0.85) and compressed real DEF pools into a narrow upper band on ownership scores.
+- **MID/FWD**: unchanged — multiplier 1.0, ceiling `VALUE_CEILING` (24.3).
+
+The same four families (target, differential, waiver, value) use analogous per-position ceilings: `GK_TARGET_CEILING` / `DEF_TARGET_CEILING`, etc. Ownership-family ceilings (target / differential / waiver) include headroom for the consistency bonus (max 0.75 target/waiver, 0.375 differential) so a top-pool player with high `cv_xgi_percentile` is not silently clamped to 100 and losing the consistency signal's discrimination. A DEF pool spanning scrub→elite shows a spread of ~30 points across the 0-100 range on each family, up from ~5 points pre-fix.
 
 **quality_per_m**: `quality_score / price` (per £m). Within-position budget efficiency - higher means more output per pound. Not meaningful for cross-position comparison. Null when price is 0.
 

{fplkit-1.2.0 → fplkit-1.2.1}/fpl_cli/_version.py

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

{fplkit-1.2.0 → fplkit-1.2.1}/fpl_cli/agents/analysis/transfer_eval.py

@@ -9,6 +9,7 @@ from fpl_cli.api.fpl import FPLClient
 from fpl_cli.services.player_scoring import (
     ConsistencySignals,
     ScoringContext,
+    _as_position,
     _value_weights_and_ceiling,
     apply_adjusted_npxg,
     apply_consistency,
@@ -238,7 +239,9 @@ class TransferEvalAgent(Agent):
             q_dict = evaluation.as_quality_dict()
             te_weights, te_ceiling = _value_weights_and_ceiling(player.position_name)
             mins_factor = calculate_mins_factor(player.minutes, player.appearances, next_gw_id)
-            raw = calculate_player_quality_score(q_dict, te_weights, mins_factor)
+            raw = calculate_player_quality_score(
+                q_dict, te_weights, mins_factor, position=_as_position(player.position_name),
+            )
             quality_score = normalise_score(raw, te_ceiling)
             if identity.price > 0:
                 quality_per_m = round(quality_score / identity.price, 1)

{fplkit-1.2.0 → fplkit-1.2.1}/fpl_cli/cli/allocate.py

@@ -12,7 +12,7 @@ from rich.table import Table
 
 from fpl_cli.cli._context import console
 from fpl_cli.cli._json import emit_json, emit_json_error, json_output_mode, output_format_option
-from fpl_cli.services.player_scoring import STARTING_XI_CEILING, VALUE_CEILING, normalise_score
+from fpl_cli.services.player_scoring import normalise_score, pick_display_ceiling
 
 if TYPE_CHECKING:
     from fpl_cli.services.squad_allocator import ScoredPlayer, SquadResult
@@ -141,12 +141,11 @@ def allocate_command(
                 console.print(Panel(msg, title="Allocation Failed", border_style="red"))
                 raise SystemExit(1)
 
-        ceiling = STARTING_XI_CEILING if horizon == 1 else VALUE_CEILING
         _emit_result(
             result, scoring_data, scored_players,
             budget, horizon, start_gw, is_json,
             bench_discount=bd, bench_boost_gw=bench_boost_gw,
-            free_transfers=free_transfers, ceiling=ceiling,
+            free_transfers=free_transfers,
         )
 
     asyncio.run(_run())
@@ -164,7 +163,6 @@ def _emit_result(
     bench_discount: dict[str, float] | None = None,
     bench_boost_gw: int | None = None,
     free_transfers: int = 1,
-    ceiling: float = VALUE_CEILING,
 ) -> None:
     """Format and output the solver result."""
     player_lookup = {sp.player.id: sp for sp in result.selected_players}
@@ -181,7 +179,7 @@ def _emit_result(
     ):
         team = team_map.get(sp.player.team_id)
         team_short = team.short_name if team else "???"
-        q_score = normalise_score(sp.raw_quality, ceiling)
+        q_score = normalise_score(sp.raw_quality, pick_display_ceiling(sp.position, horizon))
         role = "starter" if sp.player.id in result.starter_ids else "bench"
         captain_gws = captain_gws_by_player.get(sp.player.id, [])
 

{fplkit-1.2.0 → fplkit-1.2.1}/fpl_cli/cli/stats.py

@@ -101,6 +101,30 @@ def stats_command(
         sort_field = "quality_per_m"
         explicit_value_sort = False
 
+    # --value without -p produces a cross-position ranking that is not meaningful:
+    # quality_score is an elite-within-position index, so ordering elite DEFs against
+    # elite MIDs on quality_per_m actively misleads. Surface the warning in both
+    # channels so tables and JSON pipelines get the same signal:
+    #
+    #   - table mode: human-readable prose on stderr
+    #   - JSON mode:  structured entry in metadata.warnings (agent-native — agents
+    #                 parse JSON, not stderr ANSI)
+    #
+    # The metadata warning is a list of dicts so additional warnings can be added
+    # later without breaking existing consumers.
+    _cross_position_warning = (
+        value
+        and position is None
+        and sort_field in _VALUE_SORT_FIELDS
+    )
+    if _cross_position_warning and output_format != "json":
+        error_console.print(
+            "[yellow]Warning: --value without --position produces a cross-position "
+            "ranking. quality_score and quality_per_m are elite-within-position "
+            "indices; comparing GK/DEF against MID/FWD is not meaningful. "
+            "Re-run with --position GK|DEF|MID|FWD for a reliable ranking.[/yellow]"
+        )
+
     fmt = ctx.obj.format if isinstance(ctx.obj, CLIContext) else None
     show_draft = fmt in (Format.DRAFT, Format.BOTH)
 
@@ -281,10 +305,24 @@ def stats_command(
             # Limit
             filtered = filtered[:limit]
 
+            warnings: list[dict[str, str]] = []
+            if _cross_position_warning:
+                warnings.append({
+                    "code": "cross_position_ranking_not_meaningful",
+                    "message": (
+                        "quality_score and quality_per_m are elite-within-position "
+                        "indices. Sorting across all positions mixes incompatible "
+                        "scales (GK/DEF ceilings differ from MID/FWD). Re-run with "
+                        "--position GK|DEF|MID|FWD for a reliable ranking, or "
+                        "consume raw_quality for a position-agnostic proxy."
+                    ),
+                })
+
             metadata = {"gameweek": None, "format": str(fmt) if fmt else None,
                         "custom_analysis": custom_on,
                         "filters": {"position": position, "sort": sort_field,
-                                    "limit": limit, "min_minutes": min_minutes}}
+                                    "limit": limit, "min_minutes": min_minutes},
+                        "warnings": warnings}
 
             if not filtered:
                 if output_format == "json":

{fplkit-1.2.0 → fplkit-1.2.1}/fpl_cli/services/player_scoring.py

@@ -12,7 +12,7 @@ import dataclasses
 import functools
 from collections.abc import Mapping
 from math import inf
-from typing import TYPE_CHECKING, Any, Literal, overload
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
 if TYPE_CHECKING:
     from fpl_cli.api.core_insights import MatchRecord
@@ -90,7 +90,11 @@ class QualityWeights:
             penalty_xg=zero,
             gk_saves_per_90=StatWeight(1.5, 6),
             gk_xgc_quality=StatWeight(3.0, 3.5),
-            gk_cs_rate=StatWeight(8.0, 4.0),
+            # Halved 2026-04-10: was (8.0, 4.0) - a Phase 1 placeholder that
+            # put 50%-CS GKs within 0.8pt of the cap, crowding out xGI signals.
+            # At mult=4 the theoretical cap is unchanged (min(1.0*4, 4)=4) so
+            # ceiling constants stay valid; only sub-cap contributions drop.
+            gk_cs_rate=StatWeight(4.0, 4.0),
         )
 
 
@@ -149,6 +153,8 @@ VALUE_QUALITY_WEIGHTS = QualityWeights(
 )
 
 # Position multiplier: adjusts ceiling for per-game scoring potential (captain + bench)
+Position = Literal["GK", "DEF", "MID", "FWD"]
+
 POSITION_SCORE_MULTIPLIER: dict[str, float] = {
     "FWD": 1.0,
     "MID": 1.0,
@@ -156,6 +162,18 @@ POSITION_SCORE_MULTIPLIER: dict[str, float] = {
     "GK": 0.7,
 }
 
+
+def _as_position(value: str) -> Position:
+    """Narrow an enum-derived position string to the Position literal.
+
+    Raises ValueError on unknown values (e.g. the "???" fallback from
+    Player.position_name when the FPL enum is out of sync). Callers
+    passing a known PlayerPosition-derived string should never trip this.
+    """
+    if value not in POSITION_SCORE_MULTIPLIER:
+        raise ValueError(f"Unknown position: {value!r}")
+    return cast(Position, value)
+
 ATTACKING_POSITIONS: frozenset[str] = frozenset({"MID", "FWD"})
 
 
@@ -180,17 +198,107 @@ STARTING_XI_CEILING = 33.2
 # Practical ceiling ~24.3 (elite MID scores ~20 raw). Validated: Salah-tier -> 87-92/100
 VALUE_CEILING = 24.3
 
-# GK-specific ceilings — computed from GK signal caps (saves 6, xgc 3.5, cs 4)
-# plus position-appropriate form/ppg caps and matchup/ownership contributions.
-# Note: 1.38 = form_trajectory_max(1.2) * xgi_sustainability_max(1.15)
-# GK_TARGET: saves 6 + xgc 3.5 + cs 4 + form_cap(5)*1.38 + ppg_cap(4) + matchup 6
-GK_TARGET_CEILING = 30.4
-# GK_DIFFERENTIAL: saves 6 + xgc 3.5 + cs 4 + form_cap(7)*1.38 + ppg_cap(4) + ownership 5 + matchup 6
-GK_DIFFERENTIAL_CEILING = 38.2
-# GK_WAIVER: saves 6 + xgc 3.5 + cs 4 + form_cap(7)*1.38 + ppg_cap(4.8) + matchup 6 + position_need 5
-GK_WAIVER_CEILING = 39.0
-# GK_VALUE: saves 6 + xgc 3.5 + cs 4 + form_cap(7)*1.38 + ppg_cap(5) (no matchup for value)
-GK_VALUE_CEILING = 28.2
+# Non-quality bonus caps used when deriving ceiling constants. Keep in sync
+# with _matchup_bonus, the ownership bonus in _calculate_quality_based_raw,
+# and the position-need bonus in calculate_waiver_score.
+_MATCHUP_MAX = 6.0           # matchup_avg_3gw max 8.0 * 0.75 * mins_factor 1.0
+_OWNERSHIP_MAX = 5.0         # (semi_differential_threshold 15 - 0) / divisor 3
+_POSITION_NEED_MAX = 5.0     # calculate_waiver_score empty-slot bonus
+# Form multipliers applied inside calculate_player_quality_score. The ATK
+# path gets form_trajectory_max(1.2) * xgi_sustainability_max(1.15) = 1.38;
+# GK/DEF paths get form_trajectory_max only because compute_xgi_sustainability
+# returns 1.0 for non-ATK positions. The ATK form ceiling is hand-rolled into
+# the TARGET/DIFFERENTIAL/VALUE constants above (see the `form N*1.38` terms);
+# _NON_ATK_FORM_MAX is used by _gk_quality_cap and _def_quality_cap below.
+_NON_ATK_FORM_MAX = 1.2
+
+# Consistency bonus headroom — added inside _calculate_quality_based_raw.
+# cv_xgi_percentile in [0,1] × magnitude × 0.5 = max bonus. Value family
+# skips _calculate_quality_based_raw entirely and takes no consistency term.
+_CONSISTENCY_MAX_TARGET = 0.75   # (1.0 - 0.5) * CONSISTENCY_CV_TARGET (1.5)
+_CONSISTENCY_MAX_DIFF = 0.375    # (1.0 - 0.5) * CONSISTENCY_CV_DIFF (0.75)
+_CONSISTENCY_MAX_WAIVER = 0.75   # waiver uses CONSISTENCY_CV_TARGET too
+
+
+def _gk_quality_cap(weights: QualityWeights) -> float:
+    """Theoretical max of calculate_player_quality_score on the GK path.
+
+    Derived from weight caps, pre-attenuation. Matches the signal set
+    evaluated inside calculate_player_quality_score when weights.for_gk()
+    is used: saves, xgc, cs, form (trajectory only — xgi_sustainability
+    is always 1.0 for GK, see compute_xgi_sustainability), ppg.
+    """
+    gk = weights.for_gk()
+    return (
+        gk.gk_saves_per_90.cap
+        + gk.gk_xgc_quality.cap
+        + gk.gk_cs_rate.cap
+        + gk.form.cap * _NON_ATK_FORM_MAX
+        + gk.ppg.cap
+    )
+
+
+def _def_quality_cap(weights: QualityWeights) -> float:
+    """Theoretical max of calculate_player_quality_score on the DEF path.
+
+    Matches the signal set under weights.without_xgi(): form (trajectory
+    only — xgi_sustainability is always 1.0 for DEF), ppg, and
+    dc_per_90. xGI family, GK components and penalty_xg are zeroed by
+    without_xgi().
+    """
+    defw = weights.without_xgi()
+    return (
+        defw.form.cap * _NON_ATK_FORM_MAX
+        + defw.ppg.cap
+        + defw.dc_per_90.cap
+    )
+
+
+# Position-specific ceilings — derived at import so a weight change
+# auto-propagates. Quality components attenuated by
+# POSITION_SCORE_MULTIPLIER[position]; matchup, ownership and
+# position-need bonuses are added un-attenuated. Drift is guarded
+# empirically by TestCeilingValidationBands (elite-player bounds).
+_GK_MULT = POSITION_SCORE_MULTIPLIER["GK"]
+_DEF_MULT = POSITION_SCORE_MULTIPLIER["DEF"]
+# Ownership-family ceilings include _CONSISTENCY_MAX_* headroom so a top-pool
+# player with high cv_xgi_percentile does not overflow the ceiling and get
+# silently clamped to 100 (losing the consistency signal's discrimination).
+# MID/FWD TARGET_CEILING / DIFFERENTIAL_CEILING / WAIVER_CEILING already bake
+# this in (see the cv_* terms in their derivation comments above); GK and DEF
+# must add it explicitly because their caps are computed programmatically.
+GK_TARGET_CEILING = (
+    _gk_quality_cap(TARGET_QUALITY_WEIGHTS) * _GK_MULT + _MATCHUP_MAX + _CONSISTENCY_MAX_TARGET
+)
+GK_DIFFERENTIAL_CEILING = (
+    _gk_quality_cap(DIFFERENTIAL_QUALITY_WEIGHTS) * _GK_MULT
+    + _OWNERSHIP_MAX + _MATCHUP_MAX + _CONSISTENCY_MAX_DIFF
+)
+GK_WAIVER_CEILING = (
+    _gk_quality_cap(WAIVER_QUALITY_WEIGHTS) * _GK_MULT
+    + _MATCHUP_MAX + _POSITION_NEED_MAX + _CONSISTENCY_MAX_WAIVER
+)
+# Value family has no matchup or consistency — compute_quality_value skips
+# _calculate_quality_based_raw entirely.
+GK_VALUE_CEILING = _gk_quality_cap(VALUE_QUALITY_WEIGHTS) * _GK_MULT
+
+# DEF ceilings: derived from without_xgi() caps, not MID-anchored ceilings.
+# Replaces the former _position_ceiling("DEF", ...) scaling which produced a
+# mathematical no-op on the VALUE family (both numerator and denominator
+# scaled by 0.85) and a MID-anchored ceiling on target/diff/waiver that
+# compressed real DEF pools into a narrow upper band.
+DEF_TARGET_CEILING = (
+    _def_quality_cap(TARGET_QUALITY_WEIGHTS) * _DEF_MULT + _MATCHUP_MAX + _CONSISTENCY_MAX_TARGET
+)
+DEF_DIFFERENTIAL_CEILING = (
+    _def_quality_cap(DIFFERENTIAL_QUALITY_WEIGHTS) * _DEF_MULT
+    + _OWNERSHIP_MAX + _MATCHUP_MAX + _CONSISTENCY_MAX_DIFF
+)
+DEF_WAIVER_CEILING = (
+    _def_quality_cap(WAIVER_QUALITY_WEIGHTS) * _DEF_MULT
+    + _MATCHUP_MAX + _POSITION_NEED_MAX + _CONSISTENCY_MAX_WAIVER
+)
+DEF_VALUE_CEILING = _def_quality_cap(VALUE_QUALITY_WEIGHTS) * _DEF_MULT
 
 # ---------------------------------------------------------------------------
 # Consistency scoring magnitudes (Phase 2)
@@ -702,6 +810,8 @@ def calculate_player_quality_score(
     player: Mapping[str, Any],
     weights: QualityWeights,
     mins_factor: float = 1.0,
+    *,
+    position: Position | None = None,
 ) -> float:
     """Shared baseline quality score from form, PPG, and xGI/npxG.
 
@@ -711,7 +821,9 @@ def calculate_player_quality_score(
     mins_factor scales per-90 attacking components (npxG, xGChain, xGI
     fallback, penalty_xG) to discount inflated rates from low-minutes
     players. Form, ppg, dc_per_90, and GK signals (saves, xgc_quality,
-    cs_rate) are unscaled.
+    cs_rate) are unscaled. When *position* is supplied the final score
+    is attenuated by POSITION_SCORE_MULTIPLIER[position]. Default None
+    is for formula unit tests that pass naked dicts without a position.
     """
     per90 = 0.0
 
@@ -752,6 +864,9 @@ def calculate_player_quality_score(
         cs = player.get("gk_cs_rate", 0) or 0
         score += min(cs * weights.gk_cs_rate.multiplier, weights.gk_cs_rate.cap)
 
+    if position is not None:
+        score *= POSITION_SCORE_MULTIPLIER[position]
+
     return score
 
 
@@ -1472,15 +1587,55 @@ def build_scoring_enrichment(
     return enrichment
 
 
+def _target_ceiling_for(position: str) -> float:
+    if position == "GK":
+        return GK_TARGET_CEILING
+    if position == "DEF":
+        return DEF_TARGET_CEILING
+    return TARGET_CEILING
+
+
+def _differential_ceiling_for(position: str) -> float:
+    if position == "GK":
+        return GK_DIFFERENTIAL_CEILING
+    if position == "DEF":
+        return DEF_DIFFERENTIAL_CEILING
+    return DIFFERENTIAL_CEILING
+
+
+def _waiver_ceiling_for(position: str) -> float:
+    if position == "GK":
+        return GK_WAIVER_CEILING
+    if position == "DEF":
+        return DEF_WAIVER_CEILING
+    return WAIVER_CEILING
+
+
 def _value_weights_and_ceiling(position: str) -> tuple[QualityWeights, float]:
     """Select VALUE_QUALITY_WEIGHTS variant and ceiling for a position."""
     if position == "GK":
         return VALUE_QUALITY_WEIGHTS.for_gk(), GK_VALUE_CEILING
     if position == "DEF":
-        return VALUE_QUALITY_WEIGHTS.without_xgi(), VALUE_CEILING
+        return VALUE_QUALITY_WEIGHTS.without_xgi(), DEF_VALUE_CEILING
     return VALUE_QUALITY_WEIGHTS, VALUE_CEILING
 
 
+def pick_display_ceiling(position: str, horizon: int) -> float:
+    """Position + horizon aware ceiling for `fpl allocate` display normalisation.
+
+    At horizon <= 1 (single-GW lineup context) returns STARTING_XI_CEILING as
+    a cross-position anchor — a deliberate asymmetry retained until the
+    single-GW lineup ceilings are split per position. Use ``raw_quality`` if
+    you need a position-agnostic ranking in that context. horizon >= 2 uses
+    the VALUE family ceilings, matching `fpl player` / `fpl stats --value` /
+    `fpl transfer-eval` for cross-command consistency.
+    """
+    if horizon <= 1:
+        return STARTING_XI_CEILING
+    _, ceiling = _value_weights_and_ceiling(position)
+    return ceiling
+
+
 @overload
 def compute_quality_value(
     player: Any,
@@ -1539,7 +1694,9 @@ def compute_quality_value(
     q_dict = evaluation.as_quality_dict()
     weights, value_ceiling = _value_weights_and_ceiling(player.position_name)
     mins_factor = calculate_mins_factor(player.minutes, player.appearances, next_gw_id)
-    raw_score = calculate_player_quality_score(q_dict, weights, mins_factor)
+    raw_score = calculate_player_quality_score(
+        q_dict, weights, mins_factor, position=_as_position(player.position_name),
+    )
     if raw:
         return raw_score
     q_score = normalise_score(raw_score, value_ceiling)
@@ -1955,7 +2112,10 @@ def _calculate_quality_based_raw(
     )
 
     score = calculate_player_quality_score(
-        evaluation.as_quality_dict(), effective_weights, mins_factor,
+        evaluation.as_quality_dict(),
+        effective_weights,
+        mins_factor,
+        position=_as_position(evaluation.position),
     )
 
     # Ownership bonus (differential only)
@@ -2018,7 +2178,7 @@ def calculate_target_score(
     next_gw_id: int,
 ) -> int:
     """Calculate a target score (pure performance, no ownership bias)."""
-    ceiling = GK_TARGET_CEILING if evaluation.position == "GK" else TARGET_CEILING
+    ceiling = _target_ceiling_for(evaluation.position)
     return _calculate_quality_based_score(
         evaluation,
         weights=TARGET_QUALITY_WEIGHTS,
@@ -2034,7 +2194,7 @@ def calculate_differential_score(
     next_gw_id: int,
 ) -> int:
     """Calculate a differential score for a player."""
-    ceiling = GK_DIFFERENTIAL_CEILING if evaluation.position == "GK" else DIFFERENTIAL_CEILING
+    ceiling = _differential_ceiling_for(evaluation.position)
     return _calculate_quality_based_score(
         evaluation,
         weights=DIFFERENTIAL_QUALITY_WEIGHTS,
@@ -2103,7 +2263,7 @@ def calculate_waiver_score(
         elif current_count == 2:
             score -= 2
 
-    waiver_ceiling = GK_WAIVER_CEILING if evaluation.position == "GK" else WAIVER_CEILING
+    waiver_ceiling = _waiver_ceiling_for(evaluation.position)
     return normalise_score(score, waiver_ceiling)