Skip to content

Correct the STBM pension comparison docs page (#672) - #1722

Merged
vahid-ahmadi merged 7 commits into
mainfrom
vahid-ahmadi/issue-672-pension-comparison-stbm
Oct 24, 2026
Merged

Correct the STBM pension comparison docs page (#672)#1722
vahid-ahmadi merged 7 commits into
mainfrom
vahid-ahmadi/issue-672-pension-comparison-stbm

Conversation

@vahid-ahmadi

@vahid-ahmadi vahid-ahmadi commented May 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Corrects the PolicyEngine UK and STBM pension comparison page (docs/book/programs/gov/hmrc/pensions-comparison-stbm.md), written for #672.

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):

Corrected the STBM pension comparison page (docs/book/programs/gov/hmrc/pensions-comparison-stbm.md): STBM raises the basic-rate limit and every limit above it for non-savings income, and every savings and dividend limit, rather than widening every band, its basic amount is £10,000 in its 2023-24 to 2026-27 systems, Microcosm UK imputes employer contributions from the same ONS ASHE table (P10) as STBM, PolicyEngine UK now estimates carry-forward of unused annual allowance from 2020-21, the threshold income test has been £200,000 since 2020-21, and salary sacrifice under arrangements made before 9 July 2015 can be supplied.

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/672-stbm-pension-comparison-corrections.changed.md (changed).
  • Docs and changelog only; no code changes.

🤖 Generated with Claude Code

@vahid-ahmadi
vahid-ahmadi force-pushed the vahid-ahmadi/issue-672-pension-comparison-stbm branch from 80dc988 to 9d28603 Compare October 8, 2026 14:55
vahid-ahmadi and others added 3 commits October 12, 2026 11:02
@vahid-ahmadi
Compare PolicyEngine UK pension treatment with STBM (#672)
678b434 
#672 asks for a comparison of PolicyEngine UK's pension treatment with
the Scottish Tax-Benefit Model's methodology described in the Virtual
Worlds blog post.

Persist the comparison in-repo as a docs page. The headline conclusion
is the two models compute the same aggregate fiscal cost of pension
tax relief for any given household; they differ only in presentation:

- STBM splits relief-at-source (basic rate) and the higher-rate top-up
  (via SA basic-rate-band extension);
- PolicyEngine UK combines them into a single pension_contributions_relief
  reduction in taxable income — matching the HMRC pension tax relief
  statistics methodology used as the calibration target.

The page also enumerates:

- shared mechanics (annual allowance taper, salary sacrifice, employer
  contribution exclusion from earnings),
- shared gaps (annual-allowance carry-forward not modelled in either,
  decumulation taxation beyond basic private_pension_income),
- divergences in State Pension structure (PolicyEngine UK uses the
  three-variable BSP / NSP / ASP split; STBM uses a single transfer
  per the linked blog),
- post-2024 lifetime-allowance abolition: historical LTA params
  retained for back-cast, post-2024 lump-sum allowances not yet
  modelled.

Cross-links to the pension-tax-relief and state-pension docs pages
added under #704 and #1632 respectively, so the three pages function
as a coherent pension-modelling reference.
@vahid-ahmadi @claude
Refresh the planning page against the current code and type its chang…
dbcf538 
…elog fragment

Checked every variable, parameter, path and link against main in October
2026, updated the data pipeline references to Microcosm UK, and renamed the
changelog fragment to a Towncrier type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vahid-ahmadi @claude
Drop the duplicate bullet from the changelog fragment
b9d6e10 
Towncrier's default template adds its own bullet, so a fragment that
starts with "- " renders as "- - " in CHANGELOG.md. The page itself was
rechecked against main (pension_contributions_relief,
pension_annual_allowance, personal_pension_contributions_tax,
adjusted_net_income_components, annual allowance parameters) and needs no
change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vahid-ahmadi
vahid-ahmadi force-pushed the vahid-ahmadi/issue-672-pension-comparison-stbm branch from 9d28603 to b9d6e10 Compare October 12, 2026 09:10
@vahid-ahmadi vahid-ahmadi mentioned this pull request Oct 12, 2026
Merged
MaxGhenis and others added 4 commits October 23, 2026 02:20
@MaxGhenis @claude
Merge origin/main into the STBM pension comparison branch
8cad53d 
Main already carries a later, reviewed version of this page (added by #2386
and revised on its branch through 20 October); the conflict resolves to
main's version before the page is corrected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis @claude
Correct the STBM pension comparison against STBM's source and main
c64cc6c 
STBM claims checked against ScottishTaxBenefitModel.jl at f534ca1:
- calculate_pension_taxation! raises non_savings_thresholds from the basic
  rate onwards (IncomeTaxCalculations.jl:138), so it widens the basic band
  and moves the higher limits up, not "every band".
- pension_contrib_basic_amount is £10,000 in the 2023-24 to 2026-27 rUK
  files, which the Scottish systems inherit; £3,600 before.
- In its rUK systems from 2023-24, non_savings_basic_rate points at 40%.

PolicyEngine UK claims checked against main a45baf5:
- The relief cap rises to £3,600 for relief-at-source contributions
  (utils/pensions.py).
- employer_pension_contributions is an input: Microcosm UK draws it from
  ONS ASHE Table P10 bands, the Enhanced FRS uses 3x employee contributions.
- unused_pension_annual_allowance is estimated from 2020-21 (#2536).
- Threshold income has been tested at £200,000 since 2020-21
  (taper 240,000 - 40,000), and pre-2015 salary sacrifice is an input.
- Clarified "default chargeable amount" and the Scottish starter-rate case.
- Replaced the released .added fragment with a .changed fragment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis @claude
Cover STBM's savings and dividend limits and the Enhanced FRS SPI rows
e1c615b 
From the independent review of the corrections:
- calculate_pension_taxation! also raises every savings and dividend
  threshold (IncomeTaxCalculations.jl:140-141), including the £5,000
  savings starting-rate limit and the 0% dividend band, which s. 192(4)
  does not; so the two methods differ for dividend and starting-rate
  savings income even within one band.
- In the rest-of-UK systems the 40% index means only the higher rate
  limit (£125,140) rises for non-savings income; the FIXME comment is on
  the Scottish lines too, so the page no longer cites it.
- The Enhanced FRS imputes employer contributions with a QRF on its
  SPI-based high-income records (uk-data imputations/frs_only.py).
- The alternative chargeable amount applies only when it is the larger
  (s. 227ZA(1)(c)); fragment wording fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis @claude
Limit the STBM equality claim to Scottish systems and dividends above…
ea8b31c 
… the allowance

Second-round review (STBM run in Julia and PolicyEngine UK household runs):
the savings starting-rate band shrinks with taxable non-savings income in
both models, so STBM's raised starting-rate limit and PolicyEngine UK's
deduction free the same amount; the models differ only for dividends above
the allowance. The equality holds in STBM's Scottish systems, given its
rest-of-UK 40% gross-up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis

MaxGhenis commented Oct 23, 2026

Copy link
Copy Markdown
Collaborator

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

Head: ea8b31ceb32342f97f4dcef443a028c2eb5b76b2

Context. A later, reviewed version of this page reached main through #2386 (merged 21 October 2026), and its 672.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/672-stbm-pension-comparison-corrections.changed.md. Suggested title: "Correct the STBM pension comparison page".

Review. I had a verifier check every claim against STBM's source at f534ca1 and against main, and checked each correction myself. Independent adversarial reviews followed (the reviewers ran STBM's own functions in Julia and household simulations on main): rounds 1 and 2 asked for changes, and round 3 approved this head.

Corrected (12)

STBM's method (IncomeTaxCalculations.jl at f534ca1)

  1. STBM raises the basic-rate limit and every limit above it for non-savings income (:138). It does not "widen every band".
  2. It also raises every savings and dividend limit, including the £5,000 savings starting-rate limit and the 0% dividend band (:140-141), which s. 192(4) does not.
  3. Its basic amount is £10,000 in its 2023-24 to 2026-27 systems (params/sys_20xx_ruk.jl, which the Scottish systems inherit) and £3,600 before.
  4. New note: in its rest-of-UK systems from 2023-24, non_savings_basic_rate points at 40%. There the gross-up uses 40% and only the £125,140 limit rises.

PolicyEngine UK on main
5. The relief cap rises to £3,600 for relief-at-source contributions (utils/pensions.py:54-62).
6. employer_pension_contributions is an input. Microcosm UK draws it from ONS ASHE Table P10 bands. The Enhanced FRS uses 3× employee contributions for survey respondents and a QRF on its SPI-based records (uk-data datasets/frs.py:1578-1580, imputations/frs_only.py).
7. Carry-forward is now estimated from 2020-21 (#2536). Fixed in the table.
8. The same carry-forward fix in "What neither model does".
9. The threshold income test has been £200,000 since 2020-21 (£240,000 − £40,000; FA 2020 s. 22), not only since 2023-24.
10. Salary sacrifice is treated as made after 9 July 2015 unless pension_contributions_via_salary_sacrifice_pre_2015 is supplied (pension_annual_allowance_threshold_income.py:25-35).
11. "Default chargeable amount" is explained: the alternative chargeable amount applies only when the MPAA is exceeded and it is the larger (s. 227ZA(1), s. 227B).

Comparing the two
12. The equal-relief claim is limited to STBM's Scottish systems and non-savings income. The models also differ when dividends exceed the allowance, but not for starting-rate savings, because that band shrinks with taxable non-savings income in both. The fragment wording was fixed to match.

Checked and correct (unchanged)

STBM side:

  • Gross-up by 1/(1 − basic rate) (:134-136).
  • Employer contributions and AVCs count (:113-116).
  • pension_relief_at_source is recorded (:137).
  • The taper runs on total income, and relief stops at the allowance with no charge.
  • ASHE imputation of employer contributions (Pensions.jl).
  • No carry-forward.
  • The FIXME on the taper income (:100).
  • The blog's "unsure" wording.

PolicyEngine UK side, re-run on main:

  • £110,000 employee: personal allowance £7,570, or £12,570 after a £10,000 contribution.
  • £300,000 employee contributing £100,000: adjusted income £300,000, threshold income £200,000, allowance £60,000.

Law:

  • ITA 2007 s. 58.
  • ITEPA 2003 s. 308.
  • FA 2004 ss. 227ZA, 228ZA and 228A.
  • FA 2024 (lifetime allowance abolished from 2024-25).

Also: #672 is open, and PTM057100 and all links resolve.

Outside this PR

  • programs.yaml:150-158 names the programme "Pensions Annual and Lifetime Allowance", although there are no lifetime allowance parameters.

@MaxGhenis MaxGhenis mentioned this pull request Oct 23, 2026
Closed
3 of 5 tasks
@vahid-ahmadi vahid-ahmadi changed the title Compare PolicyEngine UK pension treatment with STBM (#672) Correct the STBM pension comparison docs page (#672) Oct 23, 2026
@vahid-ahmadi
vahid-ahmadi added this pull request to the merge queue Oct 23, 2026
Merged via the queue into main with commit 654dffb Oct 24, 2026
10 checks passed
@vahid-ahmadi
vahid-ahmadi deleted the vahid-ahmadi/issue-672-pension-comparison-stbm branch October 24, 2026 08:47
@juaristi22 juaristi22 mentioned this pull request Oct 24, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vahid-ahmadi @MaxGhenis