[vahid-ahmadi]

Corrects the pension tax relief page (docs/book/programs/gov/hmrc/pension-tax-relief.md), written for #704.

The page itself is already on main: it shipped in #2386 (merged 21 October 2026), and its original .added changelog entry was released in 2.143.0. This branch has merged main, dropped the released fragment and now carries only corrections to main's copy of the page.

What this PR corrects (from its changelog fragment):

Brought the pension tax relief page (docs/book/programs/gov/hmrc/pension-tax-relief.md) up to date with main: #2488 has merged, unused annual allowance is now estimated from 2020-21 rather than defaulting to nil, defined-benefit accrual can be supplied as defined_benefit_pension_input_amount, with defined_benefit_pension_share for the workplace contributions it replaces, relevant UK earnings follow taxable employment income and trading profit before losses, relief-at-source contributions stay in income for the annual allowance charge and raise its rate limits only under the s. 192(4) condition, which HMRC's PTM056120 does not state, and s. 192(4) raises the higher rate limit as well as the basic rate limit. The worked examples were re-run on policyengine-uk 2.148.2.

The claim-by-claim review behind these corrections, with sources, is in the "Ready for hub review" comment on this PR.

• Changelog fragment: changelog.d/704-pension-tax-relief-page-corrections.changed.md (changed).
• Docs and changelog only; no code changes.

🤖 Generated with Claude Code

[MaxGhenis]

UK hub (Claude build session, for Max)
Ready for hub review

Head: 87eaa7b59d13d4e7dde95571851702f7c8517d82

Context. A later, reviewed version of this page reached main through #2386 (merged 21 October 2026), and its 704.added.md entry is already in CHANGELOG.md under 2.143.0. This branch still had the 12 October version. I merged origin/main into this branch (no rebase, no force-push), resolved the add/add conflict to main's version, deleted the released .added fragment, and corrected main's version. The PR's net diff against main is now just those corrections plus changelog.d/704-pension-tax-relief-page-corrections.changed.md. Suggested title: "Bring the pension tax relief page up to date".

Why it needed updating. Main's page predates #2488 (merged 20 October) and #2536 (merged 21 October).

Review. I had a verifier extract and check every claim, and re-ran every worked example on main myself (household simulations; script pension_examples.py). Independent adversarial reviews followed: rounds 1 to 3 asked for changes, and round 4 approved this head.

Corrected (15)

1. Restrict the ordinary ATI pension uplift to relief at source #2488 merged on 20 October 2026; the page no longer calls it open (gh api .../pulls/2488).
2. unused_pension_annual_allowance is estimated from 2020-21 from an assumed five-year history, applying s. 228A(7). It no longer "defaults to nil" (variables/gov/hmrc/pensions/unused_pension_annual_allowance.py:51-86, Fix the annual allowance on survey data, the UC benefit cap earnings threshold, relevant UK earnings and Scottish water uprating #2536). It is nil for the £100,000 example; a £50,000 employee contributing £5,000 gets £146,480.
3. Defined-benefit accrual: supply defined_benefit_pension_input_amount together with defined_benefit_pension_share. The input alone double counts, and the share alone changes nothing before 75, since defined_benefit_input_per_contribution is 1. Sources: defined_benefit_pension_input_amount.py:38-42 and pension_contributions_for_annual_allowance.py.
4. Relevant UK earnings are taxable employment income (less expenses) plus trading profit after capital allowances and the trading allowance, before losses (utils/pensions.py:6-42).
5. The tapered allowance minimum was £4,000 from 2020-21 to 2022-23 (parameters/gov/hmrc/income_tax/allowances/annual_allowance/minimum.yaml).
6. Annual allowance charge: relief-at-source contributions stay in income. Section 192(4) raises the basic and higher rate limits only if tax at the higher or additional rate would otherwise be due, and s. 192(4A) covers Scottish taxpayers (https://www.legislation.gov.uk/ukpga/2004/12/section/192; private_pension_contributions_tax.py:58-130).
7. New worked example: £45,000 employee, £20,000 relief at source and £50,000 employer contributions gives a £2,946 charge in the model; a net pay arrangement gives £2,000. HMRC's PTM056120 states no s. 192(4) condition and would give £2,000. The model follows the statute, as docs/engineering/gift-aid.md:149-155 notes.
8. Section 192(4) raises the higher rate limit as well as the basic rate limit. The top-up can be claimed outside Self Assessment, and the stated rates apply in England, Wales and Northern Ireland.
9. Relief at source worth more than the tax saved: the model gives less than the law for contributions above taxable income (£720 on £3,600) and for those coming off income taxed below 20% (dividends, the Scottish starter band).
10. Where only dividends or savings sit above the basic rate limit, the model can give more or less than the law. Re-run on main: £15,000 pay plus £60,000 dividends saves £3,648 against £2,000 in law; £12,000 plus £40,000 saves £1,308.
11. The headline, the "full marginal rate" sentence, the two-mechanism section and the "presentation question" note are now limited to income taxed at one rate.
12. Pension tax relief calculations #704 gives no year or age, so the page now says the scenarios were re-run for 2025-26 at age 40.
13. Pension tax relief calculations #704's reporter expected £0 and -£1,200, so the column is now "Total relief as an income-tax change".
14. marginal_tax_rate raises the two eldest adults' pay in turn (marginal_tax_rate.py:30-51; gov.simulation.marginal_tax_rate_adults = 2). The re-run version is 2.148.2, not 2.140.0.
15. Replaced the released .added fragment with a .changed fragment.

Checked and correct (re-run on main 2.148.2)

• Pension tax relief calculations #704 cases: income tax change -£600 and -£2,400; marginal tax rate 20% and 40%.
• £3,600 personal contribution with no earnings: £3,600 relief; as an employee contribution: £0.
• £100,000 employee paying £70,000: £70,000 relief and a £2,000 charge, falling to £0 with £10,000 carried forward.
• £110,000 employee: personal allowance £7,570, or £12,570 after a £10,000 contribution.

Law and code checked:

• FA 2004 ss. 188-194, 189(2), 190, 191(7), 192, 227, 227ZA, 228ZA, 228A and 233.
• ITA 2007 s. 58.
• PTM044100 (SSP and SMP count as relevant UK earnings; Include SSP and SMP in pension-relief earnings #2464 merged 19 October UTC). Charge income tax on statutory paternity pay #2368 is still open.

Uncertain

• Which reading of s. 192(4) HMRC applies in practice (statute or PTM056120) is a methodology question that docs/engineering/gift-aid.md already records. The page states both.