Add UK pension facts: State Pension, Pension Credit, workplace pensions, salary sacrifice and Winter Fuel Payment

[juaristi22]

Summary

Add the UK pension facts #302 asks for. Every reference period from 2023 to the latest published is ported, each from the newest release that publishes it; superseded editions are not archived. 41 new source packages and 3 extended ones add 57,252 facts.

• State Pension, Great Britain residents (Stat-Xplore SP, the 13 reference months from February 2023 to March 2026), caseload and mean weekly amount:
  • by single year of age, gender and type (dwp-state-pension-age-gender-type-february-2023-march-2026, 4,879 facts);
  • by region, type and gender (dwp-state-pension-region-type-gender-…, 2,798);
  • by category and protected payment (dwp-state-pension-category-protected-payment-…, 598);
  • caseload by weekly amount band and type (dwp-state-pension-amount-band-type-…, 429).
  • Parity at March 2026: 12,207,303 residents at a mean of £221.42 a week (13,307,794 cases in all, less 1,093,218 abroad and 7,278 with no known address). Of these, 7,084,158 are on the pre-2016 scheme and 5,123,141 on the new State Pension.
• Pension Credit, Great Britain (Stat-Xplore PC, same months), claims (one per benefit unit) and mean weekly award:
  • by region, type, partner indicator and age band (dwp-pension-credit-region-type-partner-age-…, 22,966);
  • the same cross for Great Britain (dwp-pension-credit-type-partner-age-…, 2,194);
  • by gender and type (312);
  • claims by award band and type (468).
  • Parity at March 2026: 1,380,846 claims, of which 832,322 Guarantee Credit only, 150,288 Savings Credit only and 398,237 both.
• Northern Ireland (DfC Benefits Statistics Summary, May 2026 edition, whose rolling series run from February 2023):
  • State Pension (dfc-ni-state-pension-statistics-may-2026, 275): 335,540 claimants, 152,970 of them on the new State Pension, average £227.39.
  • Pension Credit (dfc-ni-pension-credit-statistics-may-2026, 236): 60,030 claimants, 68,900 beneficiaries, average £92.88.
• Workplace pensions:
  • DWP participation and saving trends, data years 2023 to 2025 (dwp-workplace-pension-savings-trends-2009-to-2025, 936). Participation is by sector, earnings band, age and sex. Amounts saved are split by component and sector. The 2025 parity: £166.1bn saved by eligible savers (employee £44.2bn, employer £101.6bn, tax relief £20.3bn), 22.61m eligible employees participating (90%) and 24.21m of all employees.
  • The ONS summary workbook, 2023 final and 2024 provisional (ons-employee-workplace-pensions-summary-2024, 66). Its Table 1 is ported for 2023 only; the 2024 column is P1's all-ages, all-earnings row, which has one more decimal place.
  • ASHE tables P1 to P12, 2024 provisional, sheet 'All' (20 packages, 15,369 facts):
    • membership by pension type against age, industry, occupation or size of business, by weekly earnings (ons-ashe-pension-membership-by-{age,industry,occupation,business-size}-earnings-2024);
    • employee and employer contribution-rate bands by the same groupings, on the full-pay and qualifying-earnings bases (ons-ashe-{employee,employer}-contribution-bands-by-{age,industry,occupation,business-size}-2024-{full-pay,qualifying-earnings}).
• Salary sacrifice:
  • The OBR costing's Table 1.1, projections for 2027-28 to 2030-31 (obr-salary-sacrifice-costing-february-2026, 36). The salary-sacrificed base above £2,000 grows from £12.9bn to £15.1bn, and the bonus-sacrificed base from £13.0bn to £14.2bn.
  • From the HMRC policy paper, added to hmrc-salary-sacrifice-reform-2029-headcounts (3 facts to 6): the 290,000 employers operating salary sacrifice, and forgone NICs of £5.8bn in 2023-24 and £8bn projected for 2030-31.
  • Every row of HMRC private pension statistics Tables 6.1/6.2:
    • 2024-25, in hmrc-salary-sacrifice-relief-2024-25 (6 facts to 85);
    • 2023-24, in the new hmrc-pension-contribution-relief-2023-24 (85), from the July 2025 edition. That asset is gone from GOV.UK and was recovered from the UK Government Web Archive.
• Winter Fuel Payment:
  • Stat-Xplore recipients by country, age band, amount and gender, for winter 2023 to 2024 (Great Britain, 288) and winters 2024 to 2025 and 2025 to 2026 (England and Wales, 348).
  • The official statistics' region tables and beneficiaries for the three winters (412). Winter 2025 to 2026: 10,872,496 recipients and 11,003,237 beneficiaries.
  • HMRC's estimate of who the Winter Fuel Payment charge reaches (hmrc-winter-fuel-payment-charge-2025, 5 projections for 2025-26): 2.2m individuals with income over £35,000, of whom 1.3m PAYE-only and 0.9m in Self Assessment.
• Attendance Allowance (Stat-Xplore, cases with entitlement by country, award type, age band and gender, February 2023 to March 2026; 2,678).
• DWP benefit expenditure and caseload tables, Spring 2026 (dwp-benefit-expenditure-caseload-spring-2026, 882 facts to 2,674):
  • the seven ported families now run to 2030-31 as source projections;
  • added Tables 1c and 2c (caseloads by benefit, including Winter Fuel Payment and Attendance Allowance, and the pensioner blocks);
  • added the Disability_benefits sheet (expenditure and caseload).
  • Lines for benefits whose Scottish cases moved to the Scottish Government carry England and Wales from the move, as the Notes tab describes them. That covers Carer's Allowance, DLA, PIP, Attendance Allowance and Severe Disablement Allowance (including its lines in the incapacity family), and Winter Fuel Payments from 2024-25.

Code changes:

• chronicle/sources/rows.py: the Stat-Xplore parser unpivots every measure cube in a response, so one request can carry a caseload and a mean. A single-measure response unpivots exactly as before; checked on all 20 existing Stat-Xplore artifacts.
• chronicle/suite.py: the row-semantic age check reads Stat-Xplore's age labels ('66', '65-69', '90 and over', 'Under 65'), so single-year and banded ages carry evidenced age bounds.

Docs: docs/pe-uk-source-checklist.md gets a section for these packages.

• The "SPP Review NI-relief bases" row, blocked because uk-data's PDF is lost, is now ported. Its £1.2bn and £2.9bn are Table 6.2's 2023-24 NICs relief on salary-sacrificed contributions: the same July 2025 edition that uk-data's dead salary-sacrifice asset pins.

Fixes #302.

Review notes

Decisions and departures from the issue text:

• State Pension residence. The SP database has no "Country summary" field. Residence comes from the geography field's Great Britain item, so cases abroad and with no known address drop out at source, as the issue intends.
• State Pension cuts. One cross of every requested field would be about 400,000 cells a month. Instead there are four cuts, each carrying the fields the issue names.
• Pension Credit entity. Pension Credit is carried as benefit_unit, one claim per benefit unit, as in dwp-benefit-expenditure-caseload-spring-2026. The issue's proposed shape said person/claimant.
• Periods. Caseloads use period_type: month (the reference month), as the Add UK source packages for #233–#237: UC child-entitlement and nil-award crosses, award-band and Scotland histories, ONS family tables, HMRC Child Benefit, census household composition #239, UK source packages: UC payment-status × child-entitlement composition crosses #251 and UK income facts for the 2025 calibration: SPI 2023-24 Tables 3.3/3.4/3.5/3.8/3.11 and the 3.7 remainder, HMRC liabilities projections (Tables 2.1 to 2.6), ESA caseload by payment type, property rental income statistics 2026, DWP Spring 2026 expenditure tables #280 Stat-Xplore packages do. Chronicle has no point_in_time period type.
• Amount bands. State Pension bands run to "£300.00 and over", not the £150 the issue feared. Stat-Xplore offers a mean but no sum for amounts, so the mean is emitted per cell.
• Section 7a is not ported from the HTML (dwp-benefit-statistics-february-2026):
  • The summaries ended in May 2026, and Stat-Xplore carries the same series, revised, for every month from 2023.
  • The summary's State Pension and Attendance Allowance totals also count cases abroad, which have no GSS geography.
  • The Attendance Allowance package counts cases with entitlement.
• Savings trends amounts. Each edition restates every year in its own year's earnings terms. Amounts carry a price_basis filter (2025_earnings_terms) rather than a basis in the concept, so a later edition's restatement keeps the concept. Nominal amounts exist only in superseded editions, which are not archived.
• ONS ASHE coverage:
  • The P tables carry 2024 provisional only, and 2023 final is only in the summary workbook.
  • Only sheet 'All' is ported; the sex and working-pattern sheets are not.
  • The all-employees rows of P2 to P12 restate P1, P5 and P9 cell for cell and are not ported twice.
  • The employer 0% band is suppressed or [w] in every row.
  • SIC 2007 sections carry their letter. The glossary's Index of Production (B to E) and service-industry (G to U) summary categories carry their own filter.
• Publisher defects kept visible:
  • OBR Table 1.1 labels the salary-sacrifice yield row "(£m)" but prints £bn.
  • NI Pension Credit Table 9's columns are mislabelled since the August 2025 edition, so it is not ported.
  • NI State Pension averages do not say whether Get Your State Pension cases are included, so their concept relation is approximate.
• Forgone NICs. The policy paper's £5.8bn for 2023-24 does not match Table 6.2's £4.1bn (£1.2bn + £2.9bn), so it has its own concept.
• HMRC Tables 6.1/6.2.
  • The six per-line salary-sacrifice measures (hmrc.ss_*, which Microcosm selects by source_concept) and the generic relief measures emit the same cells, and each measure's notes say so.
  • HMRC words the employer net-pay contribution type differently on its NICs rows. Both values stay as printed, as the row-semantic check requires, and share one label.
• Devolved benefits in the forecast tables. The workbook frames its tables as Great Britain, but its Notes tab says Scottish cases leave a benefit's lines once executive competence moves.
  • The lines added here for those benefits are stamped England and Wales (K04000001) from the move.
  • Severe Disablement Allowance is also a line of the incapacity family ported before, and it is stamped England and Wales there too, for every year. Nothing in Microcosm binds the forecast package.
  • Lines that sum moved and unmoved benefits keep Great Britain, marked concept_relation: approximate with a note naming the parts. These are Industrial Injuries benefits, where only the disablement benefit moved, the Disability_benefits totals, which include Armed Forces Independence Payment and Access to Work, and the incapacity totals, which include SDA.
  • The outside-UK lines keep Great Britain.
• Winter Fuel Payment. Winters are stamped with the fiscal year the payments fall in. For winter 2023 to 2024, the workbook and the Stat-Xplore cube differ in every Wales and Scotland cell they share, the workbook mostly higher, by at most 311 recipients or 0.07%. DWP does not say why. The cube is the later release: DWP first put WFP statistics on Stat-Xplore on 16 September 2025, a year after the workbook. Both are kept as published, and both headers say so. The later winters agree cell for cell.
• Salary sacrifice in ASHE. How ASHE classifies salary-sacrificed contributions is not published; they are most likely employer contributions, but this is not verified.

Chronicle Governance

• Approved Chronicle agent role: ledger-source-ingestor. The following sit outside its allowed paths:
  • chronicle/suite.py, for the age evidence above;
  • chronicle/source_package.py and chronicle/bundle.py, for alias and UK bundle registration, as every package PR does;
  • db/data/**, for the artifacts;
  • docs/pe-uk-source-checklist.md, changelog.d/302.added.md and .gitattributes;
  • tests/test_issue_302_uk_pension_facts.py, following the test_issue_NNN precedent.
• Deterministic checks run:
  • Every package passes package validation, and its source suite reports zero agent-acceptance errors.
  • Every raw artifact is pinned by SHA-256 in its manifest and published to the private raw bucket.
  • The full default bundle is valid: 408,145 facts (up 57,252), 268 packages and 263 source tables. tests/test_chronicle_bundle.py is re-pinned.
  • The new semantic duplicate keys (198) are State Pension, Pension Credit and Winter Fuel Payment totals reached through more than one cut or release.
    • 16 of them differ in value: the Winter Fuel Payment 2023-24 workbook against the Stat-Xplore cube.
    • The rest agree.
  • Two warnings are new, both publisher wording: ASHE's '30 to 39' and '40 to 49' against NTS0601's 'Age 30 to 39', kept as each publisher writes them, as Emit geography.name on consumer facts so Microcosm's hierarchy can label sub-national geographies (constituencies, local authorities and regions) #266 does.
• LLM judge verdicts:
  • ledger-source-fidelity: pending specialist review. Each fact is a publisher cell or Stat-Xplore cell, with header or label guards. Tests pin the publisher parity values for every source.
  • ledger-contract: no schema or consumer-contract change.
  • ledger-boundary: pending specialist review. Only publisher levels are emitted, and publisher forecasts are source_projection. There is no uprating, aging, reconciliation or imputation.

Tests

• uv run pytest -q (the full suite, including the default-bundle rebuild) before the rebase onto main and the round-one fixes: 1,345 passed, 1 skipped. The skip is test_supabase_client, which needs POLICYENGINE_SUPABASE_URL.
• On the current head: the default-bundle test (tests/test_chronicle_bundle.py::test_build_bundle_writes_merged_consumer_contract, re-pinned after the rebase and the fixes) passes, and CI runs the full suite.
• tests/test_issue_302_uk_pension_facts.py (68 tests) covers:
  • every package's fact count, validity and 2023 start;
  • the publisher parity values for each source;
  • the England and Wales stamping of the devolved forecast lines;
  • unit tests for the multi-measure Stat-Xplore parser (including a malformed later cube, which now raises) and the age-label bounds.
• uv run ruff check chronicle policyengine_chronicle db scripts tests and ruff format --check on the edited Python files: passed.
• git diff --check origin/main: clean. The two text artifacts with publisher whitespace (the HMRC 2023-24 CSV and the Winter Fuel Payment charge note) are marked -diff in .gitattributes, as the other pinned artifacts are.

🤖 Generated with Claude Code

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 1 at 3d93e720

Verdict: nothing blocking. Every fact I rebuilt matches its publisher cell. One should-fix: the Severe Disablement Allowance lines in the DWP forecast package are stamped Great Britain in one family and England and Wales in another, for the same numbers. The rest are nits and questions.

CI. The two "no conclusion" checks are the push and pull_request runs of CI on 3d93e720. Both are still running, not stuck. They started at 08:46Z, and the last eight green runs of this workflow took 1h20m to 2h10m. The previous head f15eec61 passed both.

What I checked. I built all 44 packages (58,143 facts) from the committed artifacts and checked them against the publisher files. I used my own parsers, not the package specs.

• Stat-Xplore (11 packages, 38,738 facts).
  • Every fact is keyed back to its cube cell by field and item: 0 mismatches, 0 unmatched, and no cell used twice.
  • The only cells not ported are the all-zero series the headers list.
  • No mean is emitted for an empty cell (Stat-Xplore returns £0.00 there).
  • At March 2026 the totals agree across the four State Pension cuts (12,207,303, or 12,207,306 summed over regions) and the four Pension Credit cuts (1,380,846 / 1,380,847). The ±3 is Stat-Xplore's perturbation.
• HMRC Tables 6.1/6.2, both years.
  • 79 of 79 relief facts match the CSV row for row.
  • The three rows not ported are [z].
  • The period is tax_year opening year (2023 for "2023 to 2024").
• OBR Table 1.1. 36 of 36 match the PDF text. Paragraphs 1.6 and 1.9 support the above_2000_annual_threshold filter. The yields reproduce as base × (employee + employer) rate, e.g. 14.3 × 17.7 % ≈ 2.5, which confirms the "(£m)" label is a publisher slip for £bn.
• ONS ASHE.
  • P1 (765 facts) and P9 on both bases (613 + 642) are keyed exactly against the All sheet, with thousands scaled to jobs.
  • No numeric cell is dropped except P1's all/all row, as documented.
  • The summary workbook's Table 3 sex rows are mapped correctly.
• Other packages.
  • WFP winters are stamped with the fiscal year the payments fall in (2023, 2024, 2025), with England and Wales from 2024-25.
  • The NI parity values in the body reproduce, and the DWP savings-trends geography is GB per every sheet's source line.
• Tests. tests/test_issue_302_uk_pension_facts.py: 64 passed in 67 s.

On size: of the +445,579 lines, 440,355 are source_package.yaml specs and 4,074 are the text artifacts (CSV/HTML). The code is rows.py (+37/−31), suite.py (+32), bundle.py (+41) and source_package.py (+126 alias rows), plus 741 lines of tests.

---

1. Should-fix: Severe Disablement Allowance is stamped two ways in dwp-benefit-expenditure-caseload-spring-2026.

The new caseloads_by_benefit__severe_disablement_allowance and caseloads_directed_at_pensioners__severe_disablement_allowance lines carry K04000001. The incapacity_benefits__severe_disablement_allowance_non_contributory_invalidity_pension lines keep K03000001 (source_package.yaml:9983 onwards: total, __pensioners, __working_age, caseload and expenditure). This PR extends those lines through 2030-31.

They are the same population in the same workbook:

SDA caseload	2023-24	2025-26	2030-31
incapacity_benefits__… (stamped GB)	10,000	8,000	2,000
caseloads_by_benefit__… (stamped E&W)	10,000	8,000	2,000

Notes (L) says SDA has been England and Wales only from 2020-21. The header's "None of the seven families first ported is one of those" (:106) misses that the incapacity-benefits family carries SDA.

Suggested fix: stamp the incapacity SDA caseload and expenditure lines K04000001, keeping paid_outside_uk on the frame as elsewhere, and correct the header sentence. If you'd rather not touch facts that predate this PR, stamp at least the 2027–2030 periods it adds, and record the older ones in the checklist.

2. Question: the two "mixed coverage" lines kept as Great Britain. Industrial Injuries benefits and the Disability_benefits totals include benefits whose Scottish cases left the tables (IIDB; DLA/PIP/AA). Their GB stamp therefore over-states coverage for most of the line. Would a concept_relation: approximate, or a coverage note on the fact, be more honest than GB? I'm not asking to split them.

3. Nit: salary-sacrifice relief cells are emitted under two concepts. In both HMRC packages the six hmrc.ss_* facts are the same publisher cells as the generic hmrc.pension_contribution_*_relief{contribution_type: 'Salary sacrificed contributions'} facts. For example, ss_income_tax_relief_total is 7.2bn, and so is the generic Income Tax / salary-sacrificed / Total row. That's fine while consumers pick one family, but a union over relief concepts double counts. Please record the relation: a concept note, or source_concept on the ss_* measures pointing at the generic concept.

4. Nit: one contribution type has two filter values. Income Tax rows say "Employer contributions to net pay arrangements plus deficit reduction contributions" (e.g. hmrc/pension_contribution_relief_2023_24/source_package.yaml:1561). NICs rows say "… and on employer deficit reduction contributions". Keeping publisher wording is the house style, but it means one filter can't join Income Tax and NICs relief for the same contribution. A dimension_value_labels entry pointing both at one value would fix it without changing the guards.

5. Nit: source_rows_from_statxplore_table returns partial rows silently (chronicle/sources/rows.py:1423). If a later cube has no values, return rows hands back the earlier cubes' rows as if complete. Before this change a missing values returned []. I'd raise, or at least continue, and add a test with a two-cube response whose second cube is empty.

6. Question: Winter Fuel Payment 2023-24, two releases for the same key. Workbook and cube disagree in 16 semantic keys (≤311 recipients, ≤0.07 %), and both carry the same concept, period and geography. The body says DWP doesn't explain the difference. Could one be marked the preferred source? For example, a note that the Stat-Xplore cube is the revised series, if that's what it is. Otherwise a consumer resolving the duplicate gets an arbitrary pick.

7. Question: the price basis is in the concept name (dwp.workplace_pension_annual_saving_2025_earnings_terms, …median_contribution_2025_earnings_terms, source_package.yaml:24485). Each edition rebases, so the 2026 edition will mint a new concept family and the time series splits across concepts. Would a price_basis: 2025_earnings_terms filter on one concept serve better? The earnings bands are already in 2024 terms per Note 9, so the table carries two bases.

8. Nit: P1's all-ages, all-earnings row. It is dropped in favour of the summary workbook's Table 1, which is less precise for the shares (28 vs 28.1 for defined benefit; the job counts are identical). If one of the two has to go, I'd keep P1's decimal and drop the summary's 2024 column. The summary is still needed for 2023 final.

Not findings, noted:

• The forgone-NICs £5.8bn vs Table 6.2's £4.1bn gets its own concept.
• NI Table 9's mislabelled columns are left out.
• The WFP charge's 2025-26 stamp is flagged as this package's reading. The note also says PAYE recovery runs through 2026-27 tax codes, which fits a liability-year stamp.
• The ASHE classification of salary sacrifice is marked unverified.

All four are disclosed well.

[juaristi22]

Thanks, Vahid. All eight are addressed in c6855da, on top of the rebase onto main (a63ce50).

1. Severe Disablement Allowance (should-fix): fixed. The incapacity family's SDA lines now carry England and Wales for every year from 2023-24 to 2030-31, like the new Table 1c and 2c SDA lines. That covers the total, working-age and pensioner lines, for both caseload and expenditure.

• The SDA outside-UK line keeps the frame.
• This also moves the 2023-24 to 2026-27 facts that came in with UK income facts for the 2025 calibration: SPI 2023-24 Tables 3.3/3.4/3.5/3.8/3.11 and the 3.7 remainder, HMRC liabilities projections (Tables 2.1 to 2.6), ESA caseload by payment type, property rental income statistics 2026, DWP Spring 2026 expenditure tables #280. Nothing in Microcosm binds the forecast package, so no consumer changes.
• The header sentence is corrected: the incapacity family is the one original family that carries a moved benefit.

2. Mixed-coverage lines: now marked. Industrial Injuries benefits, the Disability_benefits totals and, now that SDA has moved, the incapacity totals keep Great Britain. Each sits in its own record set with concept_relation: approximate, and a note names which parts left Scotland's tables.

3. The ss_* cells emitted twice: recorded in notes on both sides. Each hmrc.ss_* measure's notes say the generic concept emits the same cell, and the generic salary-sacrificed measures say the reverse.

• I didn't point source_concept at the generic concept. Microcosm's salary-sacrifice targets select these facts by source_concept (ledger_selector in uk_population_targets.json), so repointing it would unbind them.
• The 2023-24 package emits the same ss_* concepts, so those selectors now match two tax years. I ran Microcosm's resolver helpers on both packages' consumer rows. The two years share one period-invariant key, so the resolver takes the latest period, as before.

4. The two employer net-pay wordings: done as you suggested. A dimension_value_labels entry gives both values the Income Tax wording. The values themselves stay as HMRC prints them on each row. Rewriting the NICs value fails the row-semantic check (row_filter_value_mismatch), because the CSV row carries the other wording.

5. Parser: fixed. source_rows_from_statxplore_table now raises ValueError when a cube has no values array, or has values that don't match the fields, instead of returning partial rows. The new tests cover a second cube that is missing, empty or short. All 31 Stat-Xplore artifacts in the repo still parse.

6. Winter Fuel Payment 2023-24: the cube is the later release, and both headers now say so. DWP first published WFP statistics on Stat-Xplore, for winter 2020 to 2021 onwards, with the 16 September 2025 release. That is a year after the 2023-24 workbook (24 September 2024), and DWP describes the Stat-Xplore figures as perturbed.

• I've kept both as published and haven't marked one preferred in the facts. Choosing between sources is the consumer's side of the line (AGENTS.md).
• The headers now tell a consumer which release is newer.

7. Price basis: done. The concepts are now dwp.workplace_pension_annual_saving and dwp.workplace_pension_median_contribution, with a price_basis filter (2025_earnings_terms). A later edition's restatement therefore keeps the concept. The earnings bands keep their "2024 earnings terms" dimension label.

8. P1: agreed. P1 now keeps its all-ages, all-earnings row (28.1 for defined benefit). The summary package keeps Table 1 for 2023 only. That takes the summary from 80 facts to 66 and P1 from 765 to 779.

Checks.

• The UK pension facts for the 2025 calibration: DWP State Pension and Pension Credit caseloads from Stat-Xplore (UK residents), Northern Ireland pensions, workplace pension contributions, and the unported pension rows of files Chronicle already archives #302 tests pass (68).
• The bundle test is re-pinned (Great Britain now 20,744 facts, after the 40 SDA facts moved) and passes locally.
• Lint and the diff check are clean.