[vahid-ahmadi]

Combines 20 docs-only PRs into one, so main gets one release instead of twenty (each merge that adds a changelog fragment triggers a version bump and a PyPI release).

Each page was re-checked against current main today and corrected where it had gone stale. The fixes are on each original PR branch; this branch takes their final files unchanged. The diff touches only docs/book/ pages and changelog.d/*.added.md fragments, with no code, parameters or tests.

Original PR	Page	Issue
#1712	programs/gov/hmrc/firm-vat.md	#1320, #1333
#1714	programs/gov/cms/child-maintenance.md	#669
#1718	assumptions/mp30k-uk-switch-plan.md	#1692
#1719	policy/indirect-tax-effects-plan.md	#1114
#1720	assumptions/non-uk-benefit-receipt-plan.md	#842
#1721	programs/gov/hmrc/pension-tax-relief.md	#704
#1722	programs/gov/hmrc/pensions-comparison-stbm.md	#672
#1723	assumptions/uk-pipeline-alignment-plan.md	#1621
#1724	validation/child-poverty-tcl.md	#1398
#1725	programs/gov/dwp/pip-points-plan.md	#1069
#1726	programs/gov/dfe/regional-childcare-plan.md	#1008
#1727	policy/future-date-announcements.md	#636
#1728	assumptions/takeup-analysis-plan.md	#1354
#1729	validation/policyengine-py-household-impact.md	#1628
#1730	validation/ubuntu-vs-macos.md	#1209
#1731	assumptions/capital-gains-distribution-plan.md	#818, #817
#1732	validation/reform-impacts-dashboard-plan.md	#806
#1735	programs/gov/ofgem/warm-home-discount-plan.md	#502
#1736	programs/gov/dwp/cold-weather-payment-plan.md	#435
#1737	programs/gov/dwp/bereavement-support-plan.md	#466, #465

The linked issues stay open: these pages are plans and diagnoses, not the implementations.

Checks:

• ruff format --check . (0.17.0) is clean, including the Python blocks in the pages.
• towncrier build --draft picks up all 20 fragments.
• No myst.yml entries are needed, because the docs build picks pages up by folder pattern.
• Cross-page links that previously depended on merge order (Correct the STBM pension comparison docs page (#672) #1722 → Update the pension tax relief docs page (#704) #1721, Correct the UK pipeline alignment docs page (#1621) #1723 → Correct the non-UK benefit receipt docs page (#842) #1720) all resolve in this branch.

axiom: n/a: documentation only, no rules or parameters change.

🤖 Generated with Claude Code

[juaristi22]

Reviewed d50ee85a9664791d6c617135fed999418762f6a9 and all 20 consolidated pages. I found no blocking model defect, but three plans need technical corrections before they guide implementation:

1. docs/book/assumptions/takeup-analysis-plan.md:95–97: restrict the numerator to eligible units too: sum(would_claim_X * eligible_X * weight) / sum(eligible_X * weight). Willingness-to-claim flags can be true for ineligible units; one eligible unit and two willing units currently gives a documented rate of 200%. Define the zero-denominator case as well.
2. docs/book/policy/future-date-announcements.md:67–71: restoring 20% on the reversal announcement date does not cancel an existing future 19% row. An executed check through fiscal-year conversion leaves 2023 at 19%. Remove or replace the cancelled row at its original effective date, retaining the announcement history in references/version control.
3. docs/book/programs/gov/dwp/bereavement-support-plan.md:72–84: a flag for bereavement within the previous 18 months can remain true across consecutive annual periods, so the proposed formula can award the initial lump sum twice. Use a payment/claim-year flag or event date for the single initial payment, and reserve the 18-month information for instalments.

Minor: docs/book/programs/gov/dwp/pip-points-plan.md:163 needs the closing ) on the DWP statistics link.

Validation: all 24 well-formed local links resolve; all six Python blocks parse; the dated-row diagnostic ran; 21 cited/primary sources checked. Captured documentation CI passes. I did not rerun the full documentation build or historical private-dataset benchmarks locally. The 20 older docs PRs can continue to be handled as superseded by this bundle.

[vahid-ahmadi]

@juaristi22 thanks for the 15 Oct review. All four points are fixed in d7ed288 (docs only).

1. Take-up rate (takeup-analysis-plan.md): the numerator is now sum(would_claim_X * eligible_X * weight), over the same eligible denominator, with a note on why. A zero denominator is reported as undefined (n/a), not 0%.
2. Reversed announcements (future-date-announcements.md): the steps now say to remove the cancelled row, or replace its value at its own effective date (20% from 6 April 2023 for the Truss case), and keep the announcement history in references and version control. The page also says why a new row at the reversal date leaves 2023 at 19%.
3. BSP initial payment (bereavement-support-plan.md): the lump sum now reads a claim-year input, bsp_initial_payment_due, so it is paid once. The 18-month window stays with the instalments in bsp_months_remaining. The page also mentions a single date-of-death input as an alternative. The Phase 3 data notes use the new names.
4. PIP points plan: closed the DWP statistics link.

The documentation build runs in CI on this push.

🤖 Generated with Claude Code

[juaristi22]

Re-reviewed d7ed2889a7bc94d69c6ca10aa8f1b1296643293c.

All four points from my 15 October review are resolved: the take-up numerator includes eligibility and defines the zero-denominator case; the cancellation example removes/replaces the original future row; the BSP initial payment uses a one-year event; and the PIP link closes correctly. All 24 relative links resolve and six Python snippets parse. Five current-model pension examples also pass; hosted documentation checks pass.

A4 — Nonblocking: distinguish gross contributions from the pension-provider top-up. In docs/book/programs/gov/hmrc/pension-tax-relief.md:30–33, the new no-earnings example calls £3,600 the basic-rate top-up. A £3,600 gross relief-at-source contribution comprises £2,880 paid by the contributor and a £720 provider claim. The model's £3,600 pension_contributions_relief output is a taxable-income deduction base, not a £3,600 cash top-up. Please use that label, and £720 when describing the provider top-up. HMRC guidance and Finance Act 2004 s.192 support the distinction.

Review status: COMPLETE. No critical findings; one new should-address documentation point.

[vahid-ahmadi]

@juaristi22 thanks, A4 is fixed in c19ce75.

docs/book/programs/gov/hmrc/pension-tax-relief.md now calls the £3,600 pension_contributions_relief a deduction from taxable income, not a cash top-up. It says a £3,600 gross relief-at-source contribution is £2,880 paid by the contributor plus the £720 the provider claims from HMRC, with a link to FA 2004 s. 192. It also says PolicyEngine does not represent the £720 as a payment, and that with no taxable income the deduction saves no income tax. On current main (340bedb) the example gives pension_contributions_relief of £3,600 for personal_pension_contributions and £0 for employee_pension_contributions, with income tax of £0 in both cases.

I checked the rest of the PR's pages for the same mix-up and found none. The relief-at-source section already describes the provider's claim as the 20% basic-rate portion. The docs build cleanly with jupyter book build --html.

The separate employment plus self-employment wording tied to #2464 will follow once #2464 merges.

🤖 Generated with Claude Code

[vahid-ahmadi]

@juaristi22 following up on item 4 of your #2464 review: with #2464 merged, the relevant UK earnings wording is updated in 0163a613d (after merging main into this branch in 63edffe74).

• pension-tax-relief.md: relevant UK earnings (FA 2004 s. 189(2)) are now described as employment income, plus employer-paid SSP and SMP (employment_benefits, per PTM044100), plus self-employment profit, with a trading loss counting as zero. It also notes that SPP still waits on Charge income tax on statutory paternity pay #2368. The "two open pull requests" paragraph now says that #2464 merged on 19 October, and that only Restrict the ordinary ATI pension uplift to relief at source #2488 is still open.
• pensions-comparison-stbm.md: the earnings-limit row now lists the same three parts.

This matches relevant_uk_earnings in utils/pensions.py on main.

🤖 Generated with Claude Code

[vahid-ahmadi]

Updated the annual allowance wording in 6659ebf to match current main and FA 2004:

• pensions-comparison-stbm.md: the taper now applies both s. 228ZA tests (adjusted income above £260,000 and threshold income above £200,000), carry-forward is the unused_pension_annual_allowance input under s. 228A (default nil), and the personal allowance paragraph now says adjusted_net_income deducts pension relief. Remaining limits stated: no money purchase annual allowance, cash-proxy pension input.
• pension-tax-relief.md: added carry-forward and the MPAA limit, and re-ran every example on 2.140.0 (all unchanged; £10,000 carried forward removes the £2,000 charge).

🤖 Generated with Claude Code

[vahid-ahmadi]

Updated the bereavement support plan page in 1d94053:

• The BSP uprating open question is now a statement: the planned rate parameters are held flat, since SI 2026/148 art 19 keeps the four amounts in SI 2017/410 reg 3 unchanged (£350, £3,500, £100, £2,500 since April 2017).
• Added a line on the War Widow's Pension split from Give War Widow's Pension its own CPI-uprated variable ahead of freezing BSP #2382 (2.135.7). bsp_reported keeps CPI uprating until the datasets move FRS code 9 out (policyengine-uk-data#578, microcosm#1222), and bsp_reported is CPI-uprated but BSP rates are frozen, and the variable is mostly War Widow's Pension #2381 tracks the freeze.

🤖 Generated with Claude Code

[juaristi22]

Re-reviewed 1d9405370acd1a577384fcadec1445c17d0f199e.

A4 is resolved: the pension text now distinguishes £3,600 gross relievable contributions/the model's deduction base from the contributor's £2,880 payment and the provider's £720 recovery, and states that the model does not add a cash top-up.

The SSP/SMP wording matches #2464's relevant-UK-earnings helper. The annual-allowance, carry-forward and default-charge text matches the current functions and override input. The prior five-case diagnostic remains applicable: the relevant relief-function AST and annual-allowance charge files are unchanged; the wrapper change is the documented SSP/SMP addition. No unchanged model suite was rerun for this prose-only delta. Hosted documentation checks pass.

All previous A1–A4/S1 points are resolved. I am approving this commit. Review status: COMPLETE; no open critical findings.