[vahid-ahmadi]

Corrects the firm-level VAT planning page (docs/book/programs/gov/hmrc/firm-vat.md), written for #1320.

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 firm-level VAT planning page (docs/book/programs/gov/hmrc/firm-vat.md): #1333 is closed as a duplicate of #1320, the proposed Firm entity no longer names a non-existent state containing entity, the data table now says FRS self-employment income is profit rather than turnover and that the FRS carries a main-job SIC division, and turnover-band counts come from ONS UK business: activity, size and location rather than Business demography.

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/1320-firm-vat-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: ae8513db5a9a612ddf30ad9eccd212c5e46b02d5

Context. This page already reached main, byte for byte, through #2386 (merged 21 October 2026; batch commit d50ee85), and its 1320.added.md entry is already in CHANGELOG.md under 2.143.0. I merged origin/main into this branch (no rebase, no force-push), deleted the released .added fragment, and corrected the page. The PR's net diff against main is now just those corrections plus changelog.d/1320-firm-vat-page-corrections.changed.md. Suggested title: "Correct the firm-level VAT planning page". Merging it with a fragment triggers a release. If the hub would rather batch the docs corrections from this run, git diff origin/main...ae8513db5 applies as one patch.

Review. I had a verifier extract and check every claim, checked each correction myself, and then ran independent adversarial reviews. Round 1 approved; round 2 asked for one wording fix; round 3 approved this head.

Corrected (12)

1. Add firm analysis files #1333 is closed (20 October 2026, "not planned", duplicate of Add firm-level VAT logic with new Firm entity #1320); only Add firm-level VAT logic with new Firm entity #1320 is open. Source: gh api repos/PolicyEngine/policyengine-uk/issues/1333.
2. The proposed Firm entity no longer copies containing_entities=["state"]. PolicyEngine UK has no state entity (policyengine_uk/entities.py:19,35,46). The block runs as written: build_entity in policyengine-core entities/helpers.py:7-15.
3. The owner role holds people, because only people are members of a group entity (core taxbenefitsystems/tax_benefit_system.py:216,220; simulation_builder.py:490-496).
4. Added core's membership rule for each build type: everyone is in exactly one firm; an unlisted person gets a one-person firm (simulation_builder.py:449-458); a situation with no firms listed puts everyone in one firm (add_default_group_entity); a dataset build must assign ids (join_with_persons).
5. FRS self-employment income is profit, not turnover (policyengine_uk/variables/input/self_employment_income.py:8).
6. The FRS does carry the main job's SIC division (policyengine_uk/variables/household/income/sic_industry_division.py:4-12, from Add employment sector (public/private) and SIC industry input variables #1785).
7. Turnover-band counts come from ONS UK business: activity, size and location, not Business demography, which has no turnover bands. Fixed in the table and in step 1 of the imputation approach.
8. The ONS reference now names that dataset: counts of VAT- and/or PAYE-based enterprises by SIC and turnover band from the IDBR (https://www.ons.gov.uk/businessindustryandtrade/business/activitysizeandlocation/datasets/ukbusinessactivitysizeandlocation).
9. Cut "This mirrors the second-stage imputation pattern discussed in Align UK model/data pipeline with US patterns: reported-anchoring, second-stage imputation, and downstream bugs #1621". Align UK model/data pipeline with US patterns: reported-anchoring, second-stage imputation, and downstream bugs #1621's second stage is a QRF for FRS-only variables, not calibration to receipts.
10. uk-vatlab "hosts the firm-level VAT analysis files linked from Add firm analysis files #1333", rather than files "used to size each step".
11. The GOV.UK thresholds link redirected; it now points to https://www.gov.uk/how-vat-works/vat-thresholds (£90,000 to register, £88,000 to deregister).
12. Replaced the released .added fragment with a .changed fragment.

Checked and correct (unchanged)

• vat applies gov.hmrc.vat.standard_rate and reduced_rate to full_rate_vat_consumption and reduced_rate_vat_consumption, then divides by vat_grossing_factor. Sources: policyengine_uk/variables/gov/hmrc/vat.py:12-23 and policyengine_uk/utils/vat.py:20-34.
• There is no business-side VAT anywhere on main (grep).
• Registration threshold £90,000 and deregistration threshold £88,000 from 1 April 2024: SI 2024/307 art. 2; VATA 1994 Sch. 1 paras 1 and 4.
• vat_change and consumer_incident_tax_revenue_change exist (variables/contrib/policyengine/consumer_incident_tax_revenue_change.py). The flat-rate scheme, VAT groups and partial exemption exist (GOV.UK). policyengine/uk-vatlab is public and linked from Add firm analysis files #1333.
• All links return 200.

Uncertain

• The "not in FRS" cell for VAT registration status: there is no such field in the model or uk-data's FRS loader, but I didn't check an FRS codebook.
• The page proposes incorporated firms that "stand alone" with no members. Core may not support an empty group instance; this is flagged in the page as something the design must handle.