Skip to content

Correct the future-dated announcements docs page (#636) - #1727

Merged
vahid-ahmadi merged 5 commits into
mainfrom
vahid-ahmadi/issue-636-future-date-announcements-doc
Oct 24, 2026
Merged

vahid-ahmadi merged 5 commits into
mainfrom
vahid-ahmadi/issue-636-future-date-announcements-doc

Conversation

@vahid-ahmadi

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

Copy link
Copy Markdown
Collaborator

Corrects the future-dated policy announcements page (docs/book/policy/future-date-announcements.md), written for #636.

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 future-dated announcements page (docs/book/policy/future-date-announcements.md): the Class 1 employee rate now lives in employee_scale.yaml, the levy and repeal wording, the 30 April caveat for mid-year NI changes, the preserve_calendar_dates wording, and a link to the dated-changes guide.

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/636-future-date-announcements-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-636-future-date-announcements-doc branch from ac761c9 to 797002f Compare October 8, 2026 14:51
vahid-ahmadi and others added 3 commits October 12, 2026 10:59
#636 (2022) asked for an explicit way to encode announced-but-not-yet-
implemented policy changes, citing the Truss "growth plan" tax cuts as
the motivating example. The feature has been live the whole time — the
date-keyed parameter values mechanism handles it natively — but it
wasn't documented.

Persist the pattern in-repo at docs/book/policy/future-date-announcements.md
covering:

- the mechanism (parameter values keyed by effective date, latest on
  or before the query date wins),
- the three common patterns:
  * announced-then-reversed (Truss mini-budget): two rows, one at
    announcement date with the announced value, one at reversal date
    with the actual landing value;
  * phased-in changes: one row per phase with separate references
    (NI thresholds through the Health & Social Care Levy + April 2024
    cuts as a worked example);
  * announced abolitions: limit value up to the effective date, then
    sentinel (.inf or 0) from that date onwards (Budget 2025
    two-child limit removal as the cross-link),
- best practices: cite every future-dated row, don't extrapolate
  beyond what was announced, use policy_date queries for back-cast
  scenarios,
- distinction from gov.contrib.* reform parameters (uncertain /
  hypothetical) vs baseline future-dated rows (announced policy).
…gelog fragment

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The personal allowance freeze to 2030-31 is now enacted by Finance Act
2026 s. 10, with s. 57 indexation from 2031-32. Use the employee NI main
rate as the phased example, link parameter files instead of a changelog
fragment and a validation page that is not on main, and drop em dashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vahid-ahmadi
vahid-ahmadi force-pushed the vahid-ahmadi/issue-636-future-date-announcements-doc branch from 797002f to dfe3e08 Compare October 12, 2026 09:09
MaxGhenis and others added 2 commits October 23, 2026 01:57
Main already carries this page (#2386) with d7ed288's corrected reversal
recipe; the conflict is resolved to main's copy. Its changelog line shipped
in 2.143.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The page reached main through #2386 (with d7ed288's reversal fix) and
its changelog line shipped in 2.143.0, so this drops the released .added
fragment and corrects main's copy:

- Parameters have been date-keyed since the 2020 initial import; the
  model did not "move to" them.
- Fiscal-year conversion covers the gov tree for 2015 to 2040.
- preserve_calendar_dates readers split the year themselves (excise.py).
- The Class 1 employee rate file was refactored into employee_scale.yaml
  (0d8ed36); the 13.25% came from HSCL Act 2021 s. 5, not the levy, and
  12% returned for earnings paid from 6 November 2022 (Repeal Act s. 2).
  Without fiscal_year_blend the mid-year changes don't reach annual
  results (#1807).
- The two-child limit removal is now enacted (2026 c. 13).
- Link the scenarios guide's dated changes for reform annualisation.

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

Copy link
Copy Markdown
Collaborator

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

Head: a60894ff7954eb28ce602ef10a32522f47031d3b

Read this first. The page is already on main through #2386 (batch commit d50ee85a9, merged 2026-10-21). Main then fixed its reversal recipe in d7ed2889a, and the changelog line shipped in 2.143.0 (CHANGELOG.md:190). As it stood, this branch would have reverted that fix (GitHub showed it CONFLICTING) and repeated the changelog line.

What this push changes:

  • Merge: merges main in 0df12ed2c and resolves the add/add conflict to main's copy.
  • Fragment: deletes the released changelog.d/636.added.md and adds changelog.d/636-future-date-announcements-corrections.changed.md (type changed, so the docs-only edit isn't held by the Fix-evidence gate).
  • Page: corrects main's copy.

Against main, the diff is now just the page corrections and the new fragment. Suggested title on landing: "Correct the future-dated announcements page".

Claims checked (main = a45baf5e4, 2.148.2)

Claim Verdict Source
Parameters are date-keyed; future rows exist true parameters/gov/dwp/universal_credit/elements/child/limit/child_count.yaml:2-5; personal_allowance/amount.yaml:32-37
"since the model moved to date-keyed values" fixed: date-keyed since the initial import d0f05315b (2020-08-07)
convert_to_fiscal_year_parameters runs at system build; 30 April default; fiscal_year_blend day-weights; preserve_calendar_dates skipped true; added "gov tree, 2015 to 2040" utils/parameters.py:100-142 (YEARS :125); tax_benefit_system.py:224
Fuel duty carries fiscal_year_blend true parameters/gov/hmrc/fuel_duty/petrol_and_diesel.yaml
"their formulas annualise explicitly" reworded: the readers split the year themselves utils/excise.py; variables/gov/hmrc/alcohol_duty/beer_duty.py:19; tobacco_duty/tobacco_duty.py:29
Personal allowance YAML excerpt (2021, 2027, 2030 rows; Finance Act 2026 s. 10 reference) true, matches the file personal_allowance/amount.yaml:9-37; https://www.legislation.gov.uk/ukpga/2026/11/section/10
File has no uprating; s. 57 indexation from 2031 true; "up to 2030" narrowed to "2021 to 2030" create_threshold_indexation.py:25-27,155-221; tests/test_threshold_indexation.py:88-89
Truss growth plan dates made precise: the 23 September 2022 plan brought the 19% cut forward to April 2023; reversed 17 October 2022 gov.uk Growth Plan 2022 and the 17 October 2022 statement (review agent's fetch)
Reversal recipe true on main (d7ed2889a); this branch had the broken one utils/parameters.py:135 (30 April sampling)
No "policy as announced on date X" switch true grep of policyengine_uk/
Excise page explains "how dated reforms are annualised" fixed: it covers excise only; now also links usage/scenarios.md "Dated changes" docs/book/usage/scenarios.md:372-417; docs/engineering/excise-duties.md:30-36
national_insurance/class_1/rates/employee/main.yaml fixed: the file was removed by 0d8ed3631; the rate is class_1.employee_scale[1].rate employee_scale.yaml:112-145; utils/ni_parameter_scales.py:24
13.25% "under the Health and Social Care Levy", 12% "when the levy was repealed" fixed: s. 5 was a temporary NIC rise for 2022-23; s. 2(1) of the Repeal Act kept it only for earnings paid before 6 November 2022 https://www.legislation.gov.uk/ukpga/2021/28/section/5/enacted; https://www.legislation.gov.uk/ukpga/2022/43/section/2
Values 13.25% / 12% / 10% / 8% true, and with no blend the annual values are 13.25% (2022), 12% (2023) and 8% (2024+) employee_scale.yaml:115-141; open issue #1807
"the most common future-dating pattern" softened to "a common": no count supports "most" none
Two-child limit row (2 until 2026-04-06, then .inf); UC child element reads it true; added that it is now enacted child_count.yaml:2-5; uc_individual_child_element.py:31-32; https://www.legislation.gov.uk/ukpga/2026/13/section/1
Cost-of-Living Payment £650 / £900 / £0 from 2024-01-01 true parameters/gov/treasury/cost_of_living_support/means_tested_households/amount.yaml:3-5
2022-04-06 NI row cites the HSCL Act 2021 and the Budget true; path updated employee_scale.yaml:116-123
gov.contrib.* is reform-side true parameters/gov/contrib/README.md:1-3
Research link title matched to the page title https://www.policyengine.org/uk/research/tax-cuts-in-prime-minister-trusss-growth-plan (200)

Corrections: 10.

Uncertain and out of scope

  • employee_scale.yaml:122 titles the 2021 Budget PDF "Autumn Budget and Spending Review 2022".
  • child_count.yaml still cites the revoked reg 24A and not the 2026 Act.

Both are parameter reference fixes, not part of this docs page.

Full claim ledger: ~/reviews/uk-hub/jobs/docs-c2/b/1727-ledger.md on Max's machine.

@vahid-ahmadi vahid-ahmadi changed the title Document future-date policy announcements (#636) Correct the future-dated announcements docs page (#636) 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 2b2966c Oct 24, 2026
10 checks passed
@vahid-ahmadi
vahid-ahmadi deleted the vahid-ahmadi/issue-636-future-date-announcements-doc branch October 24, 2026 09:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants