Add 2026 Plan 2 student loan interest rate thresholds

.beads/.gitignore

@@ -0,0 +1,29 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Keep JSONL exports and config (source of truth for git)
+!issues.jsonl
+!metadata.json
+!config.json

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in-progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,56 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo
+# - sync.branch - Git branch for beads commits (use BEADS_SYNC_BRANCH env var or bd config set)

.beads/issues.jsonl

@@ -0,0 +1,3 @@
+{"id":"policyengine-uk-5qy","title":"Update student loan validation notebook with deeper analysis","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-29T21:01:35.49966-05:00","updated_at":"2025-11-29T21:02:51.469593-05:00","closed_at":"2025-11-29T21:02:51.469593-05:00"}
+{"id":"policyengine-uk-75j","title":"Add student loan calibration targets to policyengine-uk-data","description":"Add student loan repayment and balance calibration targets to policyengine-uk-data loss function.\n\n## Proposed Calibration Targets (from SLC 2024-25 statistics)\n\n### Total Repayments by Country\n| Country | Repayments | Source |\n|---------|------------|--------|\n| England (HE) | £5.0bn | SLC 2024-25 |\n| Scotland | £203m | SLC 2024-25 |\n| Wales | £229m | SLC 2024-25 |\n| Northern Ireland | £182m | SLC 2024-25 |\n| **UK Total** | **~£5.6bn** | |\n\n### Repayments by Plan Type (England)\n| Plan | Amount | Share |\n|------|--------|-------|\n| Plan 1 | £1.9bn | 37% |\n| Plan 2 | £2.8bn | 55% |\n| Postgraduate | £0.3bn | 7% |\n| Plan 5 | £41m | 0.8% |\n\n### Number of Borrowers Repaying (England)\n- 3.0m via HMRC\n- 187k scheduled direct\n- 147k voluntary direct\n\n### Outstanding Balances\n- UK Total: £294bn (March 2025)\n\n## Implementation Notes\n1. Add targets to `loss.py` in policyengine-uk-data\n2. May need to adjust for timing (FRS year vs SLC reporting year)\n3. Consider whether to calibrate on modelled (`student_loan_repayment`) or reported (`student_loan_repayments`)\n\n## Sources\n- https://www.gov.uk/government/statistics/student-loans-in-england-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-scotland-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-northern-ireland-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-wales-2024-to-2025","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-29T21:01:37.038332-05:00","updated_at":"2025-11-30T12:42:25.851958-05:00","closed_at":"2025-11-30T12:42:25.851958-05:00"}
+{"id":"policyengine-uk-occ","title":"Research official student loan repayment aggregates for calibration","description":"## Research Findings\n\n### UK Student Loan Repayments 2024-25 (SLC Official Statistics)\n\n**England (HE):** £5.0bn total repayments\n- Plan 1: £1.9bn (37%)\n- Plan 2: £2.8bn (55%)\n- Plan 3/Postgraduate: £0.3bn (7%)\n- Plan 5: £41m (0.8%, voluntary only)\n\n**Scotland:** £203m total repayments (primarily Plan 4)\n\n**Wales:** ~£229m total repayments (6.9% increase from prior year)\n\n**Northern Ireland:** £182m total repayments\n\n**UK Total (estimated):** ~£5.6bn HE repayments\n\n### Borrowers Making Repayments (England)\n- 3.0m via HMRC (39.5% of those liable)\n- 187k scheduled direct to SLC\n- 147k voluntary direct to SLC\n\n### Outstanding Balances\n- England: £236.4bn (end March 2025)\n- Scotland: £9.4bn\n- Northern Ireland: £5.6bn\n- Wales: ~£9-10bn (estimated)\n- **UK Total: ~£260-295bn**\n\n### Sources\n- https://www.gov.uk/government/statistics/student-loans-in-england-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-scotland-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-northern-ireland-2024-to-2025\n- https://www.gov.uk/government/statistics/student-loans-in-wales-2024-to-2025","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-29T21:01:36.199753-05:00","updated_at":"2025-11-30T12:41:52.88068-05:00","closed_at":"2025-11-30T12:41:52.88068-05:00","dependencies":[{"issue_id":"policyengine-uk-occ","depends_on_id":"policyengine-uk-75j","type":"blocks","created_at":"2025-11-29T21:01:47.791464-05:00","created_by":"daemon"}]}

.beads/metadata.json

@@ -0,0 +1,5 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl",
+  "last_bd_version": "0.26.0"
+}

changelog_entry.yaml

@@ -1,6 +1,4 @@
-- bump: minor
+- bump: patch
   changes:
     added:
-      - Add ONS household interest income uprating index from National Accounts D.41g (HAXV series) that reflects actual growth in household interest received
-    changed:
-      - Update savings_interest_income variable to use ONS household interest income index for uprating instead of per capita GDP. This captures the dramatic growth in household interest income (from �16bn in 2020 to �98bn in 2024) due to interest rate rises.
+      - Add 2026 Plan 2 student loan interest rate thresholds (lower £29,385, upper £52,885) and freeze lower threshold 2027-2029 per Budget 2025

docs/book/validation/student-loan-repayments.ipynb

@@ -0,0 +1,180 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Student loan repayment validation\n",
+    "\n",
+    "This notebook compares PolicyEngine UK's calculated student loan repayments against reported repayments from the Family Resources Survey (FRS) microdata. Understanding the alignment between modelled and reported values helps assess model accuracy and identify areas for improvement."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Background\n",
+    "\n",
+    "Student loan repayments in the UK are calculated as a percentage of income above a threshold, varying by loan plan:\n",
+    "\n",
+    "- **Plan 1** (pre-2012 England/Wales, Scotland, NI): 9% of income above £24,990 (2024-25)\n",
+    "- **Plan 2** (post-2012 England/Wales): 9% of income above £27,295 (2024-25)\n",
+    "- **Plan 4** (Scotland post-2017): 9% of income above £27,660 (2024-25)\n",
+    "- **Plan 5** (England post-2023): 9% of income above £25,000 (2024-25)\n",
+    "- **Postgraduate**: 6% of income above £21,000 (2024-25)\n",
+    "\n",
+    "The FRS captures reported student loan repayments, while PolicyEngine calculates repayments based on income and loan plan type."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from policyengine_uk import Microsimulation\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "sim = Microsimulation()\n",
+    "year = 2025"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get student loan data\n",
+    "reported = sim.calculate(\"student_loan_repayments\", year).values\n",
+    "modelled = sim.calculate(\"student_loan_repayment\", year).values\n",
+    "plan = sim.calculate(\"student_loan_plan\", year).values\n",
+    "income = sim.calculate(\"adjusted_net_income\", year).values\n",
+    "weight = sim.calculate(\"person_weight\", year).values"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Student loan plan distribution\n",
+    "\n",
+    "First, let's examine the distribution of student loan plans in the weighted population:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Plan distribution (weighted)\n",
+    "plan_names = {0: \"None\", 1: \"Plan 1\", 2: \"Plan 2\", 3: \"Postgraduate\", 4: \"Plan 4\", 5: \"Plan 5\"}\n",
+    "for plan_id, name in plan_names.items():\n",
+    "    count = weight[plan == plan_id].sum() / 1e6\n",
+    "    print(f\"{name}: {count:.2f}m people\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Aggregate comparison\n",
+    "\n",
+    "Comparing total reported vs modelled repayments:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "total_reported = (reported * weight).sum() / 1e9\n",
+    "total_modelled = (modelled * weight).sum() / 1e9\n",
+    "\n",
+    "print(f\"Total reported repayments: £{total_reported:.2f}bn\")\n",
+    "print(f\"Total modelled repayments: £{total_modelled:.2f}bn\")\n",
+    "print(f\"Ratio (modelled/reported): {total_modelled/total_reported:.2f}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Individual-level alignment\n",
+    "\n",
+    "For people who report making student loan repayments, how well do our calculations align?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Filter to people with reported repayments > 0\n",
+    "has_reported = reported > 0\n",
+    "\n",
+    "if has_reported.sum() > 0:\n",
+    "    # Correlation\n",
+    "    correlation = np.corrcoef(reported[has_reported], modelled[has_reported])[0, 1]\n",
+    "    print(f\"Correlation (people with reported > 0): {correlation:.3f}\")\n",
+    "    \n",
+    "    # Match rate\n",
+    "    both_positive = (reported > 0) & (modelled > 0)\n",
+    "    match_rate = both_positive.sum() / has_reported.sum() * 100\n",
+    "    print(f\"People with both reported & modelled > 0: {match_rate:.1f}% of reporters\")\n",
+    "    \n",
+    "    # Mean values\n",
+    "    print(f\"\\nMean reported (reporters): £{reported[has_reported].mean():,.0f}\")\n",
+    "    print(f\"Mean modelled (reporters): £{modelled[has_reported].mean():,.0f}\")\n",
+    "    print(f\"Mean income (reporters): £{income[has_reported].mean():,.0f}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Analysis of discrepancies\n",
+    "\n",
+    "The relatively low individual-level correlation suggests several factors may explain differences:\n",
+    "\n",
+    "1. **Timing differences**: Reported repayments reflect actual payments made during the tax year, which may include voluntary overpayments or vary based on pay frequency and employment changes.\n",
+    "\n",
+    "2. **Employment variation**: Someone may have had periods below or above the repayment threshold during the year, while our model assumes constant annual income.\n",
+    "\n",
+    "3. **Multiple loan plans**: Some individuals may have both Plan 1 and Plan 2 loans, complicating the calculation.\n",
+    "\n",
+    "4. **Study status**: Current students may have different repayment patterns not fully captured in the model.\n",
+    "\n",
+    "5. **Plan misclassification**: The loan plan imputation in the microdata may not perfectly match individuals' actual loan types.\n",
+    "\n",
+    "Despite individual-level variation, the aggregate totals are reasonably aligned, suggesting the model captures the overall scale of student loan repayments in the UK economy."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "PolicyEngine UK's student loan repayment model produces aggregate totals within a reasonable range of reported values. The individual-level correlation is lower than for income tax calculations, reflecting the complexity of student loan timing and the limitations of annual income-based calculations. For microsimulation purposes, the model provides a reasonable approximation of student loan repayment flows, while users should be aware of these limitations when analysing individual-level impacts."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}