Document State Pension model + residual aggregate gap (#1632)

[vahid-ahmadi]

Summary

• State pension undershoot: -£12bn vs OBR, ASP/Protected Payment under-captured #1632 reported a -£12bn State Pension aggregate gap against OBR, with two diagnoses: (1) new_state_pension returned the flat max for every NEW-type retiree, (2) Protected Payment was only computed for BASIC-type recipients.
• Both have since been fixed on the formula side in PR #1634:
  • new_state_pension now pro-rates against state_pension_reported,
  • additional_state_pension extends Protected Payment to NEW-type retirees too.
• This PR persists the diagnosis and the post-Pro-rate new_state_pension by reported amount #1634 state of the model in a new docs page at docs/book/programs/gov/dwp/state-pension.md:
  • the three-variable composition (basic_state_pension + new_state_pension + additional_state_pension) and the BASIC / NEW classification settled by PR Fix state_pension_type classifying all pensioners as BASIC #1618,
  • triple-lock uprating with its active / earnings / inflation flags,
  • the residual ~£12bn gap, now narrowed to a data-side ASP under-imputation for BASIC-type retirees who reported exactly the max basic rate — a policyengine-uk-data follow-up rather than a formula gap,
  • references (Pensions Act 2014, SSCBA 1992 Part 2, OBR EFO, HoC Library triple-lock briefing).
• Pure documentation; no model behaviour change.

Test plan

• Markdown lints cleanly (tables, admonitions, links).
• Docs build job picks up the new page under programs/gov/dwp/.

🤖 Generated with Claude Code