fplkit 1.3.0__tar.gz → 1.4.0__tar.gz

{fplkit-1.3.0 → fplkit-1.4.0}/.agents/skills/gw-prep/SKILL.md

@@ -414,12 +414,17 @@ Proceed immediately (non-interactive).
 > **Data (JSON):**
 > - Status: {A1 output}
 > - pFDR: {B1 output}
+>
+> **WAIVER POOL IS AUTHORITATIVE:** `fpl waivers` output is the only source for available players. All other data (stats, form tables, squad context) is for analysis only. Never recommend a claim not present in the waivers output — Phase D1 will flag pool misses as a warning. Cross-position recommendations (e.g. dropping a MID to claim a DEF) are structurally illegal and will be blocked by Phase D1.
+>
 > - Waivers: {B3 output}
 > - Squad: {B4 output}
 > - Stats: {stats_form}, {stats_transfer_momentum}, {stats_mid_xgi}, {stats_fwd_xgi}, {stats_def_clean_sheets} (from B8)
 >
 > <!-- ADAPT: Add your own supplementary data sources here (newsletters, external reports) -->
 >
+> Additionally enforce: every waiver swap must be position-for-position (MID out → MID in, DEF out → DEF in, etc.). Cross-position swaps are illegal under FPL Draft rules.
+>
 > Produce the **Draft** section of the output template.
 
 ### C2.5 -- Transfer/Waiver Evaluation
@@ -475,6 +480,56 @@ Present a brief summary to the user:
 
 ---
 
+## Phase D1: Draft Validation (draft format only - skip if format is "classic")
+
+_Runs after Phase D file write, before Phase E. Not embed-gated._
+
+1. Write Phase B's waivers JSON (from orchestrator context, B3 output) to `/tmp/gw-prep-waivers-{N}.json`.
+2. Write Phase B's draft squad-grid JSON (from orchestrator context, B4 draft output) to `/tmp/gw-prep-squad-grid-{N}.json`.
+   - For draft-only runs, this is the `fpl squad grid --format json` output from B4.
+   - For `both` format runs, this is the `fpl squad grid --draft --format json` output from B4.
+3. Run:
+
+   ```bash
+   cd "$FPL_CLI_DIR" && source .venv/bin/activate && python "$FPL_CLI_DIR/.agents/skills/gw-prep/scripts/validate_draft_waivers.py" \
+     --recommendations-file "[YOUR_OUTPUT_DIR]/gw{N}-recommendations.md" \
+     --waivers-json /tmp/gw-prep-waivers-{N}.json \
+     --squad-grid-json /tmp/gw-prep-squad-grid-{N}.json
+   ```
+
+   Parse stdout as JSON: `{"ok": bool, "flags": [...], "warnings": [...]}`.
+   If the script cannot be found or exits non-zero unexpectedly, emit a warning and proceed to Phase E (fail-open for infrastructure errors, fail-closed only for confirmed rule violations).
+
+4. **Managed block update:** locate the sentinel block in the recommendations file:
+   ```
+   <!-- phase-d1:start -->
+   ...
+   <!-- phase-d1:end -->
+   ```
+   - If flags or warnings are non-empty: replace (or insert) the block immediately after the `## Draft` (or `## Draft League`) heading line with:
+     ```
+     <!-- phase-d1:start -->
+     > ⚠️ Draft validation:
+     > - {one line per flag/warning, e.g. "Row 1: cross-position-claim (Drop: João Pedro FWD → Claim: Pedro Porro DEF)"}
+     <!-- phase-d1:end -->
+     ```
+   - If both are empty: remove the block entirely (including sentinels) if present.
+
+5. **Split posture:**
+   - Any flag with `type == "cross-position-claim"` present → emit a **red error** in chat:
+     > ❌ Phase D1 blocked: `gw{N}-recommendations.md` contains illegal cross-position waiver swap(s):
+     > - Row {N}: Drop `{drop}` ({drop_position}) → Claim `{claim}` ({claim_position})
+     > 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 (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.
+     
+     Proceed to Phase E.
+   - No flags or warnings → silent continue to Phase E.
+
+---
+
 ## Phase E: Post-write Validation (embed-mode only)
 
 _Skip unless `squad_builder_result == "embed"`. Transfer and rederive runs do not produce a `### Classic Squad` block._

{fplkit-1.3.0 → fplkit-1.4.0}/.agents/skills/gw-prep/references/rules.md

@@ -44,6 +44,8 @@ When `mode = "squad-builder"`:
 3. **Availability likelihood** -- consider whether high-value targets are likely to be claimed by opponents with higher waiver priority.
 4. **Fixture run** -- as with classic, weight the next 3 gameweeks of fixtures rather than just the immediate one.
 5. **Maximum 5 waiver suggestions** -- for each: player to drop, player to claim, positional context, and fixture rationale.
+6. **Position-for-position only** -- FPL Draft squads are locked at 2 GK / 5 DEF / 5 MID / 3 FWD. Every waiver swap must be position-for-position (e.g. MID out → MID in). Cross-position swaps are structurally illegal and will be rejected by Phase D1.
+7. **Waiver pool discipline** -- only recommend players returned by `fpl waivers --format json`. Players appearing in other data sources (e.g. `fpl stats`) are not necessarily available; never recommend a claim not in the waiver pool.
 
 ## Transfer/Waiver Evaluation Script
 
@@ -72,6 +74,10 @@ Flag the following situations prominently:
 - **Minutes risk**: started fewer than 2 of last 4 matches
 - **Price crash**: lost 0.2+ in value over the last 5 days
 
+### Grounding rule (no fabricated stats)
+
+Momentum Alert bullets must only cite numbers that appear in the CLI/stats output already inlined into the sub-agent prompt. Do not invent derivative framings like "three straight attacking returns", "X goals in Y games", "scored in N consecutive", or "back-to-back doubles" unless the underlying per-GW breakdown is visible in the provided data. When in doubt, stick to the four defined trigger types above plus the raw form number, price delta, minutes count, and injury flag percentage — these are always available. Prose beyond those fields is a fabrication risk and must be cut.
+
 ## pFDR (Positional FDR) Analysis
 
 For each position (GK, DEF, MID, FWD):
@@ -80,6 +86,13 @@ For each position (GK, DEF, MID, FWD):
 2. Identify the 3 worst fixture runs (highest average pFDR).
 3. Cross-reference with the user's current squad to surface mismatches (e.g. holding defenders with terrible upcoming fixtures).
 
+### pFDR Overview row format
+
+- **One row per team, not per player.** Multiple squad players from the same team (e.g. Raya + Gabriel at ARS) may share a row because their fixtures are identical.
+- **Never combine players from different teams into a single row.** Their fixture paths diverge after GW1 of the window and the downstream cells cannot be populated. If two same-position players are on different teams, give them separate rows.
+- **Every cell in GW{N}..GW{N+4} must be populated** with either opponent+pFDR or `BLANK` (for blank gameweeks). A `-` in any fixture cell is a bug: re-run `fpl fixtures -g {gw}` for the missing gameweeks.
+- **Avg column** = mean pFDR across the 5 GWs, treating BLANK as excluded from the denominator.
+
 ## Selection Requirements
 
 Every recommendation must include:

fplkit-1.4.0/.agents/skills/gw-prep/scripts/validate_draft_waivers.py

@@ -0,0 +1,466 @@
+#!/usr/bin/env python3
+"""Validate Draft waiver recommendations against the live waiver pool and squad-grid.
+
+Reads a gw{N}-recommendations.md file, locates the ## Draft (or ## Draft League)
+section, parses the waiver table, and cross-checks each row against:
+  - waivers JSON: claim must be present in the pool (waiver-not-in-pool)
+  - squad-grid JSON: drop position must match claim position (cross-position-claim)
+
+Emits JSON to stdout: {"ok": bool, "flags": [...], "warnings": [...]}
+Exit code is always 0; the orchestrator (Phase D1) interprets flag types for posture.
+
+Usage:
+    python3 validate_draft_waivers.py \\
+        --recommendations-file path/to/gw34-recommendations.md \\
+        --waivers-json /tmp/waivers.json \\
+        --squad-grid-json /tmp/squad-grid.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import unicodedata
+from typing import TypedDict
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+class Flag(TypedDict, total=False):
+    type: str
+    row: int
+    claim: str
+    drop: str
+    drop_position: str
+    claim_position: str
+
+
+class Warning(TypedDict, total=False):
+    type: str
+    name: str
+
+
+class ValidatorResult(TypedDict):
+    ok: bool
+    flags: list[Flag]
+    warnings: list[Warning]
+
+
+class PoolEntry(TypedDict):
+    player_name: str
+    position: str
+    team_short: str
+
+
+class SquadEntry(TypedDict):
+    player: str
+    position: str
+    team: str
+
+
+# ---------------------------------------------------------------------------
+# Normalisation
+# ---------------------------------------------------------------------------
+
+_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()
+    # 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"))
+    # fold apostrophe variants
+    s = _APOSTROPHE_RE.sub("'", s)
+    # fold hyphen/dash variants
+    s = _HYPHEN_RE.sub("-", s)
+    # fold dots to space (handles J.Pedro vs J Pedro, B.Fernandes vs B Fernandes)
+    s = s.replace(".", " ")
+    # casefold
+    s = s.casefold()
+    # collapse whitespace
+    s = _WHITESPACE_RE.sub(" ", s).strip()
+    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(")"))
+
+
+# ---------------------------------------------------------------------------
+# Pool / squad builders
+# ---------------------------------------------------------------------------
+
+
+def _shape_check_squad(data: dict) -> bool:
+    """Return True if squad-grid JSON has the expected shape."""
+    try:
+        rows = data["data"]
+        if not rows:
+            return True
+        sample = rows[0]
+        return "player" in sample and "position" in sample
+    except (KeyError, IndexError, TypeError):
+        return False
+
+
+def _shape_check_waivers(data: dict) -> bool:
+    """Return True if waivers JSON has the expected shape."""
+    try:
+        targets = data["data"]["top_targets"]
+        if not isinstance(targets, list):
+            return False
+        if not targets:
+            return True
+        sample = targets[0]
+        return "player_name" in sample and "position" in sample
+    except (KeyError, TypeError):
+        return False
+
+
+def build_pool(waivers_data: dict) -> dict[tuple[str, str], PoolEntry]:
+    """Build {(position, normalised_name) -> entry} from waivers JSON."""
+    pool: dict[tuple[str, str], PoolEntry] = {}
+    for entry in waivers_data.get("data", {}).get("top_targets", []):
+        pos = entry.get("position", "")
+        key = (pos, normalise(entry.get("player_name", "")))
+        pool[key] = entry
+    return pool
+
+
+def build_squad(squad_data: dict) -> dict[tuple[str, str], SquadEntry]:
+    """Build {(position, normalised_name) -> entry} from squad-grid JSON."""
+    squad: dict[tuple[str, str], SquadEntry] = {}
+    for entry in squad_data.get("data", []):
+        pos = entry.get("position", "")
+        key = (pos, normalise(entry.get("player", "")))
+        squad[key] = entry
+    return squad
+
+
+# ---------------------------------------------------------------------------
+# Section / table parsing
+# ---------------------------------------------------------------------------
+
+_DRAFT_HEADING_RE = re.compile(r"^## Draft(?: League)?\s*$")
+_WAIVER_SUBHEADING_RE = re.compile(r"^###\s+Waiver Recommendations\s*$", re.IGNORECASE)
+
+
+def locate_draft_section(lines: list[str]) -> tuple[int, int] | None:
+    """Return (start, end) line indices for the ## Draft / ## Draft League section."""
+    start: int | None = None
+    for i, line in enumerate(lines):
+        if _DRAFT_HEADING_RE.match(line):
+            start = i
+            break
+    if start is None:
+        return None
+    # end is next ## heading or EOF
+    for i in range(start + 1, len(lines)):
+        if re.match(r"^## \S", lines[i]):
+            return (start, i)
+    return (start, len(lines))
+
+
+def locate_waiver_subsection(section_lines: list[str]) -> list[str]:
+    """Return the slice of section_lines bounded by ### Waiver Recommendations.
+
+    Bounds end at the next ### or ## heading. Falls back to the full section if
+    the subheading is absent (older report formats).
+    """
+    start: int | None = None
+    for i, line in enumerate(section_lines):
+        if _WAIVER_SUBHEADING_RE.match(line):
+            start = i + 1
+            break
+    if start is None:
+        return section_lines
+    for i in range(start, len(section_lines)):
+        if re.match(r"^##+\s+\S", section_lines[i]):
+            return section_lines[start:i]
+    return section_lines[start:]
+
+
+def parse_waiver_table(
+    section_lines: list[str],
+) -> tuple[list[str], list[dict[str, str]]] | None:
+    """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.
+    """
+    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:
+        return None
+    return headers, rows
+
+
+# ---------------------------------------------------------------------------
+# Name resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_in_pool(
+    name: str, position: str, pool: dict[tuple[str, str], PoolEntry]
+) -> PoolEntry | None:
+    """Exact match then last-token fallback, both position-scoped."""
+    norm = normalise(name)
+    # exact
+    if (position, norm) in pool:
+        return pool[(position, norm)]
+    # last-token fallback: check if norm equals last token of any pool entry at this pos
+    for (pos, pool_norm), entry in pool.items():
+        if pos != position:
+            continue
+        if pool_norm.split()[-1] == norm:
+            return entry
+        # also handle: pool entry is short, rec file has full name
+        if norm.split()[-1] == pool_norm:
+            return entry
+    return None
+
+
+def _resolve_in_squad(
+    name: str, squad: dict[tuple[str, str], SquadEntry]
+) -> list[SquadEntry]:
+    """Return all squad entries matching name (exact, else last-token fallback).
+
+    Exact matches short-circuit the fallback. Callers inspect the list length and
+    the set of positions to decide whether the match is unambiguous.
+    """
+    norm = normalise(name)
+    exact = [entry for (_, squad_norm), entry in squad.items() if squad_norm == norm]
+    if exact:
+        return exact
+    return [
+        entry
+        for (_, squad_norm), entry in squad.items()
+        if squad_norm.split()[-1] == norm or norm.split()[-1] == squad_norm
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Core validation
+# ---------------------------------------------------------------------------
+
+
+def validate_rows(
+    rows: list[dict[str, str]],
+    pool: dict[tuple[str, str], PoolEntry],
+    squad: dict[tuple[str, str], SquadEntry],
+    squad_shape_ok: bool,
+    waivers_shape_ok: bool = True,
+) -> tuple[list[Flag], list[Warning]]:
+    flags: list[Flag] = []
+    warnings: list[Warning] = []
+
+    for i, row in enumerate(rows, start=1):
+        drop_raw = row.get("Drop", "")
+        claim_raw = row.get("Claim", "")
+        position = row.get("Position", "").strip()
+
+        if _is_placeholder(drop_raw) or _is_placeholder(claim_raw):
+            continue
+
+        # Resolve claim in pool (position-scoped). Skip when waivers shape is unknown —
+        # an empty pool would otherwise mark every real claim as a false positive.
+        claim_entry: PoolEntry | None = None
+        if waivers_shape_ok:
+            claim_entry = _resolve_in_pool(claim_raw, position, pool)
+            if claim_entry is None:
+                flags.append(
+                    Flag(
+                        type="waiver-not-in-pool",
+                        row=i,
+                        claim=claim_raw,
+                    )
+                )
+
+        # Resolve drop in squad (all positions, to find actual position)
+        if not squad_shape_ok:
+            continue
+        drop_candidates = _resolve_in_squad(drop_raw, squad)
+        if not drop_candidates:
+            warnings.append(Warning(type="drop-not-resolvable", name=drop_raw))
+            continue
+        drop_positions = {e["position"] for e in drop_candidates}
+        if len(drop_positions) > 1:
+            # Ambiguous last-token match across positions — can't determine drop_pos safely
+            warnings.append(Warning(type="drop-ambiguous-match", name=drop_raw))
+            continue
+        drop_entry = drop_candidates[0]
+
+        # Cross-position check
+        claim_pos = claim_entry["position"] if claim_entry else position
+        drop_pos = drop_entry["position"]
+        if drop_pos != claim_pos:
+            flags.append(
+                Flag(
+                    type="cross-position-claim",
+                    row=i,
+                    drop=drop_raw,
+                    drop_position=drop_pos,
+                    claim=claim_raw,
+                    claim_position=claim_pos,
+                )
+            )
+
+    return flags, warnings
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def _run(recommendations_file: str, waivers_json: str, squad_grid_json: str) -> None:
+    flags: list[Flag] = []
+    warnings: list[Warning] = []
+
+    # Load waivers
+    with open(waivers_json, encoding="utf-8") as f:
+        waivers_data = json.load(f)
+
+    # Load squad-grid
+    with open(squad_grid_json, encoding="utf-8") as f:
+        squad_data = json.load(f)
+
+    # Shape checks
+    squad_shape_ok = _shape_check_squad(squad_data)
+    if not squad_shape_ok:
+        warnings.append(Warning(type="squad-grid-shape-unknown"))
+
+    waivers_shape_ok = _shape_check_waivers(waivers_data)
+    if not waivers_shape_ok:
+        warnings.append(Warning(type="waivers-json-shape-unknown"))
+
+    pool = build_pool(waivers_data) if waivers_shape_ok else {}
+    squad = build_squad(squad_data) if squad_shape_ok else {}
+
+    # Load recommendations
+    with open(recommendations_file, encoding="utf-8") as f:
+        content = f.read()
+    lines = content.split("\n")
+
+    # Locate draft section
+    section_range = locate_draft_section(lines)
+    if section_range is None:
+        warnings.append(Warning(type="draft-section-not-found"))
+        result: ValidatorResult = {"ok": True, "flags": [], "warnings": warnings}
+        json.dump(result, sys.stdout)
+        return
+
+    start, end = section_range
+    section_lines = lines[start:end]
+
+    # Narrow to the ### Waiver Recommendations subsection so we don't ingest
+    # rows from the Starting XI / Bench tables that follow it.
+    waiver_lines = locate_waiver_subsection(section_lines)
+
+    # Parse waiver table
+    table = parse_waiver_table(waiver_lines)
+    if table is None:
+        warnings.append(Warning(type="waiver-table-not-found"))
+        result = {"ok": True, "flags": [], "warnings": warnings}
+        json.dump(result, sys.stdout)
+        return
+
+    headers, rows = table
+    if "Drop" not in headers or "Claim" not in headers:
+        warnings.append(Warning(type="drop-claim-columns-not-found"))
+        result = {"ok": True, "flags": [], "warnings": warnings}
+        json.dump(result, sys.stdout)
+        return
+
+    # Validate rows
+    row_flags, row_warnings = validate_rows(
+        rows, pool, squad, squad_shape_ok, waivers_shape_ok
+    )
+    flags.extend(row_flags)
+    warnings.extend(row_warnings)
+
+    ok = len(flags) == 0
+    result = {"ok": ok, "flags": flags, "warnings": warnings}
+    json.dump(result, sys.stdout)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Validate Draft waiver recommendations against the waiver pool and squad.",
+    )
+    parser.add_argument(
+        "--recommendations-file",
+        required=True,
+        metavar="PATH",
+        dest="recommendations_file",
+        help="Path to gw{N}-recommendations.md.",
+    )
+    parser.add_argument(
+        "--waivers-json",
+        required=True,
+        metavar="PATH",
+        dest="waivers_json",
+        help="Path to fpl waivers --format json output.",
+    )
+    parser.add_argument(
+        "--squad-grid-json",
+        required=True,
+        metavar="PATH",
+        dest="squad_grid_json",
+        help="Path to fpl squad grid --format json output (draft squad).",
+    )
+    args = parser.parse_args()
+    _run(args.recommendations_file, args.waivers_json, args.squad_grid_json)
+
+
+if __name__ == "__main__":
+    main()

{fplkit-1.3.0 → fplkit-1.4.0}/.claude/output-styles/fpl-mate.md

@@ -18,6 +18,24 @@ You are an FPL mate - the kind who's run five mini-leagues, watches xG religious
 - No emojis unless requested
 - No time estimates
 
+## Decision Heuristics
+
+Never reason from a wrong rule. If you're unsure about a scoring or mechanics detail, say so and check `docs/fpl-rules.md` - don't guess.
+
+- **Banking the FT is a live option.** FTs bank up to 5. Skipping a transfer buys flexibility next week, not wasted currency. Always weigh it against a marginal move.
+- **Formation is a variable.** Valid: 3-4-3, 3-5-2, 4-3-3, 4-4-2, 4-5-1, 5-3-2, 5-4-1. Evaluate transfers against the 15-man squad, not a fixed XI - a same-position swap can mean "both play via reshape", not "one replaces the other". Compare all candidate sells at that position before committing.
+- **Hit threshold: >8 pts expected gain** across the planning horizon before eating a -4.
+- **Bench Boost = all 15 score once (not 2x).** Floor-raiser via bench minutes, not a multiplier.
+- **Triple Captain = captain scores 3x (not 2x).**
+- **Chip availability:** each chip twice per season, split at GW19. Check `fpl chips` before assuming.
+
+## Draft Rules (load-bearing)
+
+- **Waiver claims must be position-for-position.** Squad composition is fixed at 2 GK / 5 DEF / 5 MID / 3 FWD. Dropping a FWD means claiming a FWD, full stop. No cross-position swaps.
+- **Waiver pool is only what `fpl waivers` returns.** Never recommend a player who isn't in that output, even if they look great in `fpl stats`. Premium names (Haaland, Salah, Palmer etc.) are almost always owned - check the waiver JSON, don't assume.
+- **If no player is available at the position you need, say so.** Park the dead-weight asset and focus waiver priority elsewhere. Don't manufacture a bad cross-position claim to fill the slot.
+- **Draft has no captain, no budget, no chips, no transfers.** Only waivers and trades.
+
 ## FPL Expertise
 
 You have strong opinions and will argue them:

{fplkit-1.3.0 → fplkit-1.4.0}/AGENTS.md

@@ -46,6 +46,9 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 ### Exception Handling
 - Never use bare `except Exception`. Use specific types for narrow try blocks; use `# noqa: BLE001 — <justification>` for intentional broad handlers (agent top-level, scraper resilience, graceful degradation)
 
+### Timestamps
+- User-facing timestamps (deadlines, kickoffs, `generated_at` stamps) must route through `fpl_cli/utils/time.py` (`format_deadline`, `format_kickoff`, `format_generated_at`, `now_uk`). Never `strftime` on a naive `datetime.now()` or print raw API ISO strings to users. Tool is UK-locked: display is always `Europe/London` with GMT/BST label. Internal datetime math stays UTC.
+
 ## FPL Domain Knowledge
 - Chips (each available **twice** per season, split at GW19 deadline): Wildcard, Free Hit, Bench Boost, Triple Captain
 - Scoring: GK/DEF clean sheet = 4pts, MID = 1pt; goals: DEF=6, MID=5, FWD=4; assist = 3pts; yellow = -1; red = -3

{fplkit-1.3.0 → fplkit-1.4.0}/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [1.3.0] - 2026-04-17
+
+### Bug Fixes
+
+- correct stats key names and draft trailing heading (#19)
+- inject explicit chip roster into synthesis prompt
+- six LLM/formatting fixes for gw review output (#26)
+- use custom team-ratings FDR in GW fixtures table when custom_analysis enabled
+- drop understat position from enrichment spread
+
+### Features
+
+- embed squad-builder output on wildcard/freehit weeks (#23)
+- surface active chips in recap narrative
+- detect bench boost chip and adjust analysis emphasis
+- chip-aware analysis for WC, FH, BB, and TC (#24)
+- WhatsApp-friendly standings text block (#25)
+
+### Refactoring
+
+- consolidate ownership ceiling dispatch into single helper
+- thread Position literal through scoring pipeline (#21)
+- rename horizon=1 output field to single_gw_score (#22)
+- tighten project SKILL.md prompt contract and phase ordering
+
 ## [1.2.1] - 2026-04-10
 
 ### Bug Fixes

{fplkit-1.3.0 → fplkit-1.4.0}/CLAUDE.md

@@ -46,6 +46,9 @@ For a complete inventory of CLI commands, analysis agents, and skills with JSON
 ### Exception Handling
 - Never use bare `except Exception`. Use specific types for narrow try blocks; use `# noqa: BLE001 — <justification>` for intentional broad handlers (agent top-level, scraper resilience, graceful degradation)
 
+### Timestamps
+- User-facing timestamps (deadlines, kickoffs, `generated_at` stamps) must route through `fpl_cli/utils/time.py` (`format_deadline`, `format_kickoff`, `format_generated_at`, `now_uk`). Never `strftime` on a naive `datetime.now()` or print raw API ISO strings to users. Tool is UK-locked: display is always `Europe/London` with GMT/BST label. Internal datetime math stays UTC.
+
 ## FPL Domain Knowledge
 - Chips (each available **twice** per season, split at GW19 deadline): Wildcard, Free Hit, Bench Boost, Triple Captain
 - Scoring: GK/DEF clean sheet = 4pts, MID = 1pt; goals: DEF=6, MID=5, FWD=4; assist = 3pts; yellow = -1; red = -3

{fplkit-1.3.0 → fplkit-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fplkit
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli
@@ -19,6 +19,7 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: ruamel-yaml>=0.18.0
+Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
 Provides-Extra: dev
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'

{fplkit-1.3.0 → fplkit-1.4.0}/docs/architecture.md

@@ -551,7 +551,10 @@ fpl_cli/
 │   └── fpl_prices.py             # FPLPriceScraper (needs FPL_EMAIL/FPL_PASSWORD)
 ├── paths.py                      # SHIPPED_CONFIG_DIR, TEMPLATE_DIR, user_config_dir(), user_data_dir()
 ├── season.py                     # season_label() (+ vaastav_season() alias), TOTAL_GAMEWEEKS, CHIP_SPLIT_GW
-└── constants.py                  # MIN_MINUTES_FOR_PER90
+├── constants.py                  # MIN_MINUTES_FOR_PER90
+└── utils/
+    ├── text.py                   # strip_diacritics (name matching across sources)
+    └── time.py                   # format_deadline/format_kickoff/format_generated_at — UK local (Europe/London, auto GMT↔BST). Canonical formatter for every user-facing timestamp.
 
 platformdirs (user_config_dir / user_data_dir)  # macOS: ~/Library/Application Support/fpl-cli/
 ├── settings.yaml                 # User overrides, created by `fpl init`