[juaristi22]

External users need a cohesive explanation of the UK household pipeline alongside Microcosm's implementation runbooks. Add /methodology/uk covering sources and imputation, small-area household assignment, joint national/constituency/local-authority calibration, changes from Enhanced FRS, and validation limits.

The page reuses the homepage's fonts, colour tokens, animated household field, navigation and footer, hero buttons, diagram styles and scroll reveals. It opens with a short summary of which dataset PolicyEngine certifies for UK analysis today and which file serves national and local results. It adds a responsive contents list, source and target tables, a pipeline diagram (sources, household records, the national and local routes, area assignment, calibration against official statistics and each route's checks), key terms, what is fitted for Scotland, what a release must pass, nation-specific limits, version history and pinned implementation references. Navigation wraps on narrower desktop and tablet screens so the page's extra navigation link stays visible.

The page is version 0.6, a draft describing Microcosm revision 90ff43f9575fb5ae5c0c4389ba4790ab4ade5722, which locks policyengine-uk 2.162.8. The next release is being built on that revision with policyengine-uk 2.162.12 and one unreleased engine change, without changing the method. The page names the release policyengine.py 6.11.1 serves today (built at 67ee2ddf3 with policyengine-uk 2.151.0) and marks the changes planned for the next release. Enhanced FRS 1.58.1 appears as the predecessor: the last Enhanced FRS release PolicyEngine certified before policyengine.py 6.10.0 made Microcosm the UK default, and the benchmark a national Microcosm release must still beat. The page does not certify a dataset release or publish validation figures. Until editorial and technical review are complete it carries noindex, and the homepage links to it as a draft: the release walkthrough says it uses US data and that the UK page is currently a draft for editorial review, followed by a button to the page. The navigation and footer link to it too.

Add editorial and contributor instructions (methodology/EDITING.md, methodology/AGENTS.md) that keep the public narrative focused, require human editorial and technical review before publication, and list what to change at publication. .github/CODEOWNERS names the UK data maintainer and a technical reviewer for /methodology/.

What version 0.6 changes

• Release status: Microcosm UK is the dataset PolicyEngine certifies (policyengine.py 6.10.0 onwards). Each release has a national file and a separate local-area file for constituency and local-authority analyses, and policyengine.py certifies both files together. A new "Which file PolicyEngine uses" note explains that the two files are calibrated separately, so constituency results add up to the local-area file's national total.
• Enhanced FRS: now described as the predecessor. A national release must fit shared targets better than a pinned Enhanced FRS file, and both builds keep an input-mass parity check against it. policyengine.py no longer loads its area weight matrices.
• Local route: Broad Rental Market Areas and private rents follow the assigned area in Great Britain. The exact-size release holds 150,000 households. Rotated holdouts and the Enhanced FRS comparison are optional for a local release. The page lists the criteria that block a local release.
• Sources and stages: the seven stages added since 866fee4 (annual income for HMRC targets, regional Land Registry home values, property purchases, Universal Credit take-up by family type and award, Move to Universal Credit, Carer's Allowance take-up, childcare take-up for added copies).
• Targets and Scotland: Scotland's 18 BRMA private-rent rows, high-value homes for local authorities only, the 400-home small-cell rule, and Universal Credit cells counting households with a payment.
• Diagram and wording: the diagram groups the official statistics the way it groups the sources, and its caption is gone. The overview separates imputation from calibration. Instead of describing the methods in depth, the imputation and calibration sections link the imputation working paper, the calibration working paper (in preparation) and the L0 working paper.
• Planned for the next release: constituency energy targets, single-adult discount targets, apprentice flags, and alcohol, tobacco and gambling duty inputs. They reach users only if that release passes its checks.
• Access: the released files derive from the licensed surveys and are not publicly downloadable.
• References: every Microcosm link re-pinned to 90ff43f95. The benefit-cap reference moves to policyengine_uk/utils/benefit_cap.py at the 2.162.8 tag. New links cover policyengine.py's release notes and UK region routing, the localisation steps and the small-cell rule.

Validation

• Checked the page's claims against Microcosm at 90ff43f95, policyengine-uk 2.162.8 (the version Microcosm locks at that revision), policyengine.py 6.11.1 (its changelog, region routing and bundle manifest) and Enhanced FRS 1.58.1 (daad71c). The FRS sample sizes come from DWP's background note and the Scottish Government's poverty statistics, not from the build. Every number on the page is a published figure, a code parameter, a version, or a count of stages, targets or areas. None comes from a release's diagnostics.
• Rendered at 1280 and 390 px wide: no page-level horizontal scroll; the diagram's text fits its boxes, and on phones the diagram scrolls inside its container with a hint saying so. Both tables fit at 390 px.
• One h1, unique IDs, no missing anchor targets, balanced tags, and 27 reference markers that match the 10-item list. 39 of the 41 unique external links return 200; the canonical URL and the documentation-source link 404 until merge. The three working-paper links resolve on microcosm.institute.
• git diff --check passes. The site is static HTML on the existing Vercel configuration, with no build step or general site test suite.

Before publication

• Complete editorial and technical review. Then remove noindex and the homepage's draft wording, update the status line and record the review date, as methodology/EDITING.md describes.
• Turn on "Require review from Code Owners" for master. It is a repository setting and needs an admin.
• Decide the public contact route (currently the Microcosm issues page). Release fit and support figures stay with licensed users; any public summary of them needs a disclosure review first.
• Re-pin to the next release once policyengine.py certifies it. Name that release, remove the "planned for the next release" markers and update what changed. Draft Re-pin the UK methodology to the next certified release (placeholder) #91 holds that update.
• Add the prepared companion link to the Microcosm README once this page is live.

Refs #83. The issue remains open until the reviewed page is published and the Microcosm README links to it.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
microcosm-institute	Ready	Preview	Oct 27, 2026 5:14pm UTC

[vahid-ahmadi]

Automated review pass (Claude Code, high effort) — round 1 at 2d2eabd4

Verdict: the text is accurate and carefully scoped. I checked every mechanism claim against Microcosm at e3e3d881 and found nothing wrong. One should-fix is about publishing, not content: merging puts a draft that says it's pending review on the homepage nav and footer.

What checks out

• Sources and vintages match uk/spec/sources.yaml at e3e3d881:
  • FRS 2024–25 (UKDS SN 9563);
  • SPI 2022–23 Public Use Tape (SN 9422);
  • WAS round 8, 2020–22, GB (SN 7215);
  • LCFS 2023–24 (SN 9468);
  • ETB (SN 8856) with the NHS activity/cost table;
  • NTS 19th edition (SN 5340).
• Stages and the national route match docs/uk-full-build-graph.md. The national role has no ladder and no local surface.
• Geography:
  • 2021 OAs for England and Wales, 2022 OAs for Scotland, 2021 Data Zones for Northern Ireland;
  • drawn within the FRS region by census household count;
  • identity-keyed draws;
  • 2024 constituencies and April 2023 local authorities (uk_pcon_2024, uk_lad_2023, local_area_crosswalk.json).
• Calibration:
  • capped relative-error loss, solved with Adam;
  • grain_equal, with national, constituency and local-authority rows each taking an equal share of the objective;
  • weight-ratio bound 10 (uk_runtime/local_doctrine.py:48-74);
  • precedence country, then constituency, then local authority, with lower grains rescaled to the winner (docs/uk-local-cross-grain-reconciliation-802.md:5-7);
  • rotated local holdout with 5 folds (local_rowwise.py:81).
• Target table: tenure, rents and council-tax bands are scoped to local authorities only, which matches the target register.
• Enhanced FRS comparison:
  • Country-restricted area weights are confirmed at policyengine-uk-data c61798e (create_country_mask).
  • The benefit-cap example holds: benefit_cap.py reads the household's region == LONDON.
• No overclaiming:
  • No fit figures and no ESS threshold.
  • The local dataset isn't described as approved.
  • Copies aren't described as extra observations.
  • The page says the comparison against the earlier pipeline is a release requirement, not a result.
• Licensing: the line saying respondent-level data isn't redistributable is right. The MIT footer matches the repo licence.
• Links: all 15 pinned GitHub, policyengine-uk-data, policyengine-uk and ONS links return 200. The Vercel preview built.

Findings

Should

1. Publishing an unreviewed draft. The page says "Version 0.1 · draft for editorial review", and methodology/EDITING.md asks for editorial and technical approval before merging to the publishing branch. But this PR also adds the page to the homepage nav (index.html:44), the "How a release is built" section (index.html:187-192) and the footer, so merging publishes the draft and links to it.
   • Either: hold the merge until the review EDITING.md describes is done.
   • Or: merge the page without the three homepage links and with <meta name="robots" content="noindex"> until it's reviewed.

Nits

2. The footer's "releases" link goes to policyengine/populace-us (methodology/uk/index.html:230), inherited from the homepage. On the UK page it points readers to US data. Drop it on this page, or point it at a UK release listing once one is public.
3. NTS wording. "the travel stage uses declared regional proxies for devolved-country recipients" is slightly broader than the manifest. Scotland and Northern Ireland are priced from their own receipts and journeys, with England's trip rate as the proxy. Wales isn't priced and keeps the raw draw (sources.yaml, the bus-fare notes). Suggested: "…so devolved-country recipients use England's trip rates as a declared proxy; fares for Wales are not priced."
4. "Documentation source" footer link (tree/master/methodology) and the canonical URL return 404 until merge. That's expected; just check them after deploy.
5. CODEOWNERS. EDITING.md asks for .github/CODEOWNERS with required owner review on /methodology/, but the PR doesn't add it. Add it here or in a follow-up, or the review rule isn't enforced.
6. Optional: a reader can't tell from the page that a national release has been certified while local hasn't. One sentence in the status box ("a national release has been certified; no local release has been certified yet") would help, if you want the page to say that rather than stay purely about method.

[vahid-ahmadi]

Thanks María, re-reviewed at 878cad29. Verdict: the corrected text is accurate against Microcosm at e3e3d881 and Enhanced FRS 1.58.0, and the tone is neutral. What's left is publishing, not content: the draft question from round 1 is still open.

Round 1, point by point

• 1 (publishing an unreviewed draft): still open, see finding 1.
• 2 (footer "releases" link to the US repo): fixed, the UK page's footer no longer has it.
• 3 (NTS wording): fixed. methodology/uk/index.html:127 now says devolved bus use is predicted from a stand-in English region, Scotland and Northern Ireland fares are priced from their own statistics, and Welsh fares keep the drawn values. That matches the manifest.
• 4 ("Documentation source" link): fine. The default branch is master, so tree/master/methodology will resolve once this merges.
• 5 (CODEOWNERS): still open, see finding 3.
• 6 (optional status sentence): not taken, which is fine. The scope box now says the page "does not certify any dataset", which is clearer.

Findings

1. Merging still publishes a page that calls itself a draft, and the homepage now points to it more prominently.

   • The page still says "Version 0.1 · draft for editorial review" (methodology/uk/index.html:69) and "Editorial and technical review pending" (:200).
   • The new commit adds a "Read the UK methodology →" button to the homepage (index.html:192), on top of the nav link (index.html:44) and the footer link (index.html:704). There is still no noindex.
   • As before: either finish the review that methodology/EDITING.md describes and update the status line and history to match, or merge without the homepage links and with <meta name="robots" content="noindex"> until then.

2. The document metadata doesn't record today's corrections. "Prepared 8 October 2026" (methodology/uk/index.html:71) and the history entry (:200) describe only v0.1. Commit 878cad29 changes substantive claims: the copy count, the reconciliation rule, the weight bound, the Enhanced FRS comparison and the target table. For a page meant to be cited and checked, add a v0.2 entry dated 12 October 2026 saying what was corrected.

3. CODEOWNERS is still missing. methodology/EDITING.md asks for .github/CODEOWNERS with required owner review on /methodology/, and the repo has no .github/ directory. Add it here or in a follow-up, or the review rule isn't enforced.

4. Nit: "Its current release (1.58.0)" (methodology/uk/index.html:170) will go stale at the next Enhanced FRS release. "At the time of writing (1.58.0)" keeps it true.

5. Nit: the sources table is cramped on phones. At 390px, tbody th { min-width: 175px; } (methodology/methodology.css:99) leaves the "Role in the pipeline" column about 70px wide, so the SPI and WAS rows run to a word or two per line. Dropping the min-width inside the existing max-width: 500px block (:139) would fix it. There is no horizontal page scroll.

What I checked

• The diff 2d2eabd4..878cad29 against Microcosm at e3e3d881:
  • 15 copies (UK_LOCAL_CLONE_COUNT, local_doctrine.py:93);
  • the weight bound of 10, clamped every step with no lower limit, and free total mass (solve.py, rowwise_cli.py:114);
  • five rotated folds with the national rows kept in training (local_rowwise.py:1851);
  • the reconciliation order country, region, constituency, local authority (ledger_targets.py:167);
  • the local target families and their areas in uk_local_target_census.json: ten-year age bands to 79, UC by children for constituencies only, tenure for every local authority, PIPR rents in England and Wales only, council-tax bands in Great Britain. The equivalised-income family is fenced and unbound, so leaving it out of the table is right;
  • SPI copies drawn on age, sex and region, and the £200,000+ band donors taking their mass from their region, so the total is conserved (spi_band_donors.py);
  • Northern Ireland's WAS draw remapped to Wales (was_wealth.py:192), the best-fit lookups in uk_atomic_area_supports.provenance.json, and the assigned local_authority checked against the engine's domain on export (rowwise_dataset.py:507-513);
  • policyengine-uk 2.100.0 in uv.lock.
• Links: 23 of the page's 25 external links return 200. The other two, the canonical URL and the "Documentation source" link, 404 until merge, as expected.
• Enhanced FRS at 4cbedbec is version 1.58.0, with separate constituency and local-authority calibrations, each with the national matrix and a country mask (utils/calibrate.py).
• Neutrality: the Enhanced FRS section describes the difference without claiming Microcosm is more accurate, and says a measured comparison is a release requirement.
• Rendered locally with reduced motion at 1400px and 390px, plus the homepage section with the new button. The layout holds and there's no horizontal scroll. The Vercel preview needs Vercel login.

[juaristi22]

Thanks @vahid-ahmadi. Round 2 is addressed in e35b157, 0ea8bb2 and d0e6da6:

1. Draft publication (0ea8bb2): the page now carries noindex, and the homepage no longer links to it. I removed the nav link, the walkthrough button and the footer link; the walkthrough keeps one sentence saying it uses US data. methodology/EDITING.md now lists what to restore at publication.
2. Metadata (e35b157): version 0.2, prepared 12 October 2026, with a history entry listing the corrections.
3. CODEOWNERS (d0e6da6): .github/CODEOWNERS names you and me for /methodology/ and for the ownership file, and GitHub reports no errors in it. It only blocks merges once "Require review from Code Owners" is on for master, which needs admin access. Could you or Max turn it on?
4. "Its current release" (e35b157): now "At the time of writing, its latest release (1.58.0)". I also changed "Recent releases also give each household one output area…" to "That release…", because 1.57.4 and earlier did not draw that output area within the household's FRS region.
5. Phone table (e35b157): the row headers drop their minimum width at 500px and below, so the role column is about 170px wide at 390px, up from about 70px.

e35b157 also replaces the five stage cards with a pipeline diagram: sources, household records, the national and local routes, area assignment, calibration against official statistics and each route's checks. Its labels use facts already in the text, checked against the same pinned code, and it has a text description for screen readers.

[juaristi22]

@vahid-ahmadi, a follow-up on finding 1: I've changed approach in 702e192. The homepage keeps its links to the UK page (walkthrough button, nav and footer), and the walkthrough now says the page is "currently a draft for editorial review". The page keeps noindex until the review is done, and methodology/EDITING.md now says to remove the draft wording and noindex at publication. If you'd still rather not link a draft from the homepage, the alternative is to hold the merge until the review is complete.

[vahid-ahmadi]

Thanks María, read it as an SG analyst would (someone on the SFC, OCEA or Social Security Scotland analysis side) at 702e192. Verdict: it reads well and is carefully neutral, but it is a UK page that says almost nothing about Scotland, so an SG reader will finish it without knowing what is fitted, modelled or missing for Scotland.

This is separate from the accuracy review earlier today; nothing below changes those findings. Rendered locally at 1400px and 390px (the preview still needs a Vercel login).

Suggestions, most important first

1. Say up front which dataset to use today (status box above #overview). The answer is spread across the status box, #efrs and #validation, and "What changes from Enhanced FRS" is a hero button before Enhanced FRS has been defined. Suggested first lines of the status box:

   "In short: Enhanced FRS, built in policyengine-uk-data, is the dataset PolicyEngine currently certifies for UK policy analysis. Microcosm is the pipeline intended to replace it. No Microcosm local dataset has yet been released for constituency or local-authority analysis."

2. Add "What is fitted for Scotland" (#calibration, after the local table). The page only says "Available targets and coverage differ across the UK's countries", but the pipeline already fits Scottish statistics, and these are the first thing SG will ask about. Suggested paragraph, from the targets at e3e3d881 (worth checking against the current target register before it goes in):

   "For Scotland, national calibration fits Scottish Government statistics on Scottish Child Payment spending and the council-tax stock by band, ONS counts of children under 16 and babies under 1 in Scotland, and DWP's count of Scottish Universal Credit households with a child under 1. Locally, Scotland's 32 councils and 57 constituencies take the age, employment income, Universal Credit and household-count targets, and the councils also take tenure and council-tax bands. There are no Scottish private-rent targets."

   A short table (statistic, publisher, level) would read better than the paragraph if the list grows.

3. Add a Scotland entry to "Coverage differs by nation" (#validation). It currently only covers Northern Ireland. What the pipeline actually does:

   • Adult Disability Payment and Child Disability Payment are read from their FRS codes and treated like PIP and DLA; Pension Age Disability Payment and Carer Support Payment arrive under the Attendance Allowance and Carer's Allowance codes (changelog.d/1095-*). The OBR PIP, Attendance Allowance, Carer's Allowance and Winter Fuel rows bind England and Wales only, so no Scottish disability or carer payment total is a target.
   • The three income-tax rate-band targets for salary sacrifice are excluded because the band test uses rUK thresholds and ignores the Scottish bands (calibration_measure_exclusions.json).
   • Scottish Child Payment take-up comes from the Scottish Government's take-up statistics (take_up_contract.json).
   • Scottish council-tax bills exclude water and sewerage charges, and council-tax income after reduction is compared with Scottish Local Government Finance Statistics as a report-only check, not a target (local_validation_levels.json).

   Suggested bullet:

   "Scotland. Scottish Child Payment spending and council-tax bands are calibrated to Scottish Government statistics. Adult and Child Disability Payment, Pension Age Disability Payment and Carer Support Payment are carried from the FRS as reported, but no Scottish totals for them are targeted. Salary-sacrifice relief targets split by income-tax rate band are not yet fitted, because the band test does not yet apply Scottish bands. There are no Scottish private-rent targets."

4. Say where tax and benefit rules come from (#overview, end of the first paragraph). SG will look for Scottish income tax bands, LBTT, Best Start Grants and the Winter Heating Payments, and on this page they will find nothing. None of these belong in a dataset methodology, but the reader needs to be told where to look. Suggested:

   "Tax and benefit rules, including Scottish income tax rates and bands, Land and Buildings Transaction Tax and Social Security Scotland payments, are modelled in PolicyEngine-UK, not in this pipeline; see the PolicyEngine-UK documentation for which are covered."

5. Give the Scottish sample (#data, FRS row or the paragraph under the table). Small-area credibility in Scotland comes down to how many FRS households sit behind it, and #validation asks readers to read results "alongside the number of underlying source households" without saying what that is. Suggested: "The FRS 2024–25 achieved sample includes N households in Scotland [cite the DWP FRS background note]", with the figure taken from the build rather than from memory.

6. Turn "how much to trust local results" into guidance (#validation). The page explains effective sample size well but never says what a low value means for a user. Suggested:

   "Release diagnostics will report, for each constituency and local authority, the number of distinct source households and the effective sample size. Treat estimates for areas with few source households, and for narrowly defined groups within any area, as indicative. The dataset does not provide confidence intervals."

   It would also help to say where release fit figures will appear once there is a release, even if the page itself stays free of numbers.

7. Data access and contact (#version). "Several underlying surveys require licensed access" doesn't tell SG what they can and can't do. Suggested:

   "The FRS, SPI, WAS and LCFS are available from the UK Data Service under its End User Licence. The pipeline code is public under the MIT licence; rebuilding the dataset requires your own UK Data Service access. Questions: ."
   I left the contact as a placeholder: whichever address you want SG to use (hello@policyengine.org, or a named person).

   It would be better still with a named maintainer.

8. Readability: define terms where they first appear and break up two paragraphs.

   • Add a short gloss on first use, or a five-line glossary at the end of #overview, for:
     • calibration, imputation and holdout;
     • effective sample size (already defined, but only in #validation);
     • quantile regression forests (#data) and Adam (#calibration), which can probably just go, or move to a footnote.
   • Turn the "Additional stages" paragraph (#data, about 110 words in one sentence chain) and "Reconciling overlapping statistics" (#calibration) into short lists.
   • The rest of the prose is clear and well ordered.

9. Geography wording for Scottish readers (#geography). On this page "Data Zone" means Northern Ireland, while to an SG analyst Data Zones are the Scottish small-area standard. Suggested: "2022 Census Output Areas in Scotland (the building blocks of Scotland's Data Zones)".

10. Phone: the pipeline diagram hides the national route (#overview). At 390px the diagram scrolls sideways inside its box, but nothing shows that it does. Readers see the local route and half-cut boxes, and the "national route" label is off screen. Adding a small "scroll sideways" caption under 500px, or stacking the two routes, would fix it.

What works well

• The plain explanation of weights, benefit units and "copies are not extra observations" is exactly right for this audience.
• The #efrs section is fair and does not oversell.
• The limits list and the "Passing software tests ... does not establish" line will reassure a government reader.
• The pinned revision, document history and reference list make it citable.

[juaristi22]

Thanks @vahid-ahmadi, this was a useful read from the SG side. All ten suggestions are in 0a006bf (version 0.3). I checked each Scotland statement against the targets and code at e3e3d881 before adding it, and they all held.

1. Which dataset to use today: the status box now opens with an "In short" paragraph. Enhanced FRS is the dataset PolicyEngine certifies at the time of writing; Microcosm builds candidate replacements, which must pass a measured comparison with Enhanced FRS before release; and no dataset from this FRS 2024–25 pipeline has been certified yet, national or local. I went with "candidate replacements" rather than "intended to replace it".
2. What is fitted for Scotland: a new subsection in #calibration. Nationally, Scotland is one of the twelve regional rows (age, and HMRC taxpayers and income by band), plus the Scottish Government's council-tax stock by band and Scottish Child Payment spending, OBR's Scottish council-tax receipts, ONS counts of children under 16 and babies under one, DWP's Universal Credit households with a child under one, and the Scottish State Pension caseloads. Locally, the 32 councils and 57 constituencies take the age, HMRC income, Universal Credit and household-count targets, the councils also take tenure and council-tax bands, and there are no private-rent targets.
3. Scotland in the limits: your bullet is in, covering the disability and carer payments, the salary-sacrifice rate-band exclusion, water and sewerage charges, and the Scottish Local Government Finance Statistics comparison as a report-only check. Scottish Child Payment take-up is in the additional-stages list, linked to the Scottish Government's take-up publication.
4. Tax and benefit rules: the overview now says they are modelled in PolicyEngine-UK, including Scottish income tax, LBTT and Social Security Scotland payments, and links its documentation.
5. Scottish sample: "16,299 households across the UK (DWP), of which about 1,900 were in Scotland (Scottish Government)". Both figures come from the published DWP background note and the Scottish Government's poverty statistics, not from the build.
6. Reading local results: your guidance paragraph is in #validation. I haven't said yet where release fit figures will appear, because that is still a publishing decision; it is on the PR's before-publication list.
7. Data access and contact: the code is under MIT, and the survey microdata come from the UK Data Service "under its licence conditions". I couldn't confirm each survey's licence type from the catalogue, so it doesn't say End User Licence. Questions go to the Microcosm repository's issues for now; I'll swap in an address once we pick one.
8. Readability: a four-item "Key terms" list now ends #overview, the additional stages and the reconciliation rule are lists, Adam is gone, and quantile regression forests get a one-line explanation.
9. Data Zones: "2022 Census Output Areas in Scotland (the building blocks of Scotland's own Data Zones)", and the diagram now says that the Data Zones it uses are Northern Ireland's.
10. Phone diagram: a "Scroll sideways to see both routes →" hint appears above the diagram whenever it is wider than its box.

[juaristi22]

@vahid-ahmadi, an update since your last round: 113ec9e re-pins the page to Microcosm main at 866fee4 (version 0.4). I re-checked every claim at the new revision. Most held; these changed:

• LCFS: the vintage is now 2024–25 (UK Data Service SN 9603), in the sources table and the diagram.
• Incomes and property: Survey of Personal Incomes draws now take the copied adult's rank among similar FRS respondents and apply only to adults with taxable income. Landlords' rental receipts and mortgage interest now come from HMRC's Property Rental Income Statistics and the SPI. Owner-occupied households in the top 5 per cent of home values in their region are split into six records.
• Local build: in England and Wales, owner-occupied copies now take a home value from Land Registry sales in their constituency and a council-tax band from their neighbourhood's VOA band mix; the council-tax bill still comes from the source household. A local release can also be an exact 100,000-household selection, under the same checks.
• Targets: new local rows for higher-rate taxpayers (England, Wales and Northern Ireland), DESNZ domestic electricity and gas use (Great Britain), and homes worth more than £1m, £1.5m and £2m (England and Wales, estimated by Microcosm from Land Registry sales). Very small published cells are no longer fitted directly but still count towards their region's total.
• Calibration: the objective is now shared equally among four groups (UK-wide; nations and regions; constituencies; local authorities), then equally by target family, with counts weighted by the square root of their size. Reconciliation now runs in both builds, and each nation's household estimate takes precedence.
• Scotland: the salary-sacrifice rate-band targets are now fitted using Scottish bands, and the list of what is fitted adds the NRS household estimate, Capital Gains Tax, bus finance, and higher- and additional-rate taxpayers.
• References: Enhanced FRS 1.58.1 (the certified release) and PolicyEngine-UK 2.132.6.

Two corrections to version 0.3, both recorded in the document history:

• OBR's Scottish council-tax receipts are not fitted separately; only the Great Britain total is.
• The "In short" box now says that Microcosm has certified national datasets from this pipeline, while no local dataset has met the local release requirements.

[vahid-ahmadi]

@juaristi22 thanks, this is a new pass at 113ec9e.

On content: fine to merge as a draft once 1 and 2 are worded. Every changed claim I checked holds at 866fee4, and nothing on the page breaks the disclosure rules. This pass covers the content only. Whether the homepage should link to the page while it's still a draft (your 702e192 change) is a separate publishing call, which I haven't made here.

SG read (0a006bf), point by point

1. Which dataset to use today: in. The 113ec9e wording is right too. #1284 names the national cut promoted on 15 October, and policyengine.py's bundle 6.7.3 still certifies Enhanced FRS 1.58.1.
2. What is fitted for Scotland: in. Each item matches uk_population_targets.json: the Table 3.11 regional rows, higher- and additional-rate taxpayers, CGT by region, the NRS household estimate, Scottish Government council-tax stock, Scottish Child Payment spending, bus revenue and support, the under-16 and under-1 counts, UC households with a child under one, and the State Pension caseloads for Scotland. The OBR correction is right. obr.council_tax_scotland is in the register, but the Ledger compiles no value for it (ledger_compile_parity_incumbent_2025_signed_differences.json), so only the GB row binds.
3. Scotland in the limits: in. PIP, AA, CA and Winter Fuel bind England and Wales only. The salary-sacrifice bands now use each person's Scottish or rest-of-UK schedule, and none of the three is excluded any more.
4. Where tax and benefit rules live: in.
5. Scottish sample: in. Both figures match their sources. DWP gives "a total achieved sample size of 16,299" households. The Scottish Government gives "In the 2024/25 survey year the Scottish sample was 1,900 households", which is one year, not the pooled three.
6. Guidance on local results: in, apart from saying where fit figures will appear. Leaving that to the publication list is fine.
7. Data access and contact: partly. "Under its licence conditions" is a reasonable choice. The contact is still the issues page, not a named address.
8. Readability: in. There are key terms, lists, no Adam, and a one-line gloss for quantile regression forests.
9. Data Zones: in.
10. Phone diagram: in. The hint is shown by CSS at 669px and below (methodology.css:93).

Findings

1. Should: say which build "Fitting with constraints" describes (methodology/uk/index.html:329).

   • The paragraph comes right after a list that applies to "both builds". It then describes the four-group, family-equal, square-root rule as if it were general.
   • That rule is the local doctrine (local_doctrine.py:96, nation_grain_family_equal_sqrt_count). The national build uses family_equal (national_doctrine.py:41). Both share the 10x bound (national_doctrine.py:36).
   • Suggested opening: "In the local build, the objective is shared equally among four groups…", plus one clause such as "the national build gives each family of statistics an equal share".

2. Should: the sized release refit adds a penalty the page leaves out (:101, :329).

   • "Refits the selected households' weights to the same targets under the same limits" is true, but the refit also has a chi-square L2 penalty that pulls weights towards their mean. The reason given in the code is to keep effective sample size up (local_doctrine.py, UK_LOCAL_SIZE_REFIT_L2_*; dataset_size.py).
   • That trades some fit for even weights, so a reader comparing the two files should know about it. Suggested wording: "…to the same targets under the same limits, with a penalty that keeps the weights close to equal".
   • The size has also moved on main (see below). "100,000" appears four times (:101, :329, :345, :368), so it might be easier to write "an exact-size selection (100,000 households at this revision)" once and say "the selection" elsewhere.

3. Nit: home values and bands (:288).

   • "Recent HM Land Registry sale prices" undersells the method. The value comes from the latest sale of each dwelling since 1995, uprated with the UK HPI (changelog.d/1240-high-value-homes.added.md).
   • "Assigned neighbourhood" is the LSOA (property_localisation.py:15-17). Naming it would help readers who know the geography.

4. Nit: higher-rate small cells (:304, :312). Higher-rate taxpayer cells under 5,500 are also deferred, because HMRC rounds those cells to the nearest thousand (local_small_cell_rule.json). The small-cell sentence gives only the council-tax example, so the higher-rate row reads as fully fitted. One clause in the small-cell sentence would cover it.

5. Nit: high-value homes are "estimated … from HM Land Registry sales" (:238, :308). The estimate also uses the census owner-occupied share, the VOA stock for homes not sold since 1995, and OBR's 60 per cent control for homes over £2m. "From HM Land Registry sales and other published statistics" would be accurate without adding length.

6. Nit: nav wrap (index.html:44, and the same link on the UK page). Between about 1000px and 1160px the extra "UK methodology" item pushes the nav onto two rows, on both the homepage and the UK page. It already wrapped at 780 to 980px before this PR, so this only widens the range.

Already changed on main since 866fee4 (accurate at the pin; for the next re-pin, not this PR)

• The sized local release is now 150,000 households (UK_LOCAL_DATASET_HOUSEHOLDS, #1301 via #1307).
• #1302 re-pinned the Chronicle feed to abf0921, with UC paid claims, OBR rows stamped Great Britain, and local gas rows in gas-year 2024 kWh. The page's wording is general enough that none of these makes it wrong today.
• #1301 withholds per-area support figures. The page already publishes none, and areas below the floor are still named in the manifest.
• Enhanced FRS 1.58.2 was tagged on 15 October, and main's parity register now points at it. The certified bundle is still 1.58.1, so the page is right for now.

Publication checklist

• noindex is present (:9). The status line, history and homepage sentence (index.html:189) all say draft. methodology/EDITING.md:19-24 says what to change at publication.
• .github/CODEOWNERS is valid, but master has no branch protection, so code-owner review isn't enforced yet. That needs an admin.
• As expected, the canonical URL and the "Documentation source" link 404 until merge.

Disclosure, neutrality and wording

• Neither the page nor the PR's Markdown files contain microdata-derived counts, ESS figures, minima, maxima or seat-level values.
• Every number on the page is a published figure (16,299; about 1,900), a configuration constant (15 copies, ten times, five folds, 50 dwellings, 100,000), or a count of geographies.
• The wording is neutral, uses no "poor" or "rich", and headings are in sentence case. The Enhanced FRS section still says a measured comparison is a release requirement, not a result.

What I checked

• Every sentence changed in 0a006bf..113ec9e, against a shallow clone of Microcosm at 866fee4e7:
  • source_stages.json: LCFS SN 9603; the SPI recipient rule with its £1,000 floor and twin-quantile draws; predictors; property components from PRIS and SPI; the top-5% six-way split;
  • property_localisation.py: owners only, England and Wales only;
  • uk_local_target_census.json, cross_grain_declarations.json (higher rate in England, Wales and Northern Ireland; nations take precedence for households), local_small_cell_rule.json, desnz_local_energy_facts.json and the Orkney and Shetland deferrals;
  • target_weights.py, local_doctrine.py, national_doctrine.py, dataset_size.py, and local_rowwise.py:1969 (each fold reruns the selection);
  • registry.py and #1284 for the national certification;
  • uv.lock (policyengine-uk 2.132.6).
• Enhanced FRS: daad71cd is 1.58.1, the country mask is in utils/calibrate.py, and policyengine.py's bundle manifest certifies 1.58.1. The benefit_cap.py at 1a31ef1 reads the household's region.
• Links: all 33 unique external links return 200, except the two expected 404s.
• Render: the Vercel preview needs a login, so I served the PR locally and used headless Chromium with reduced motion at 390px and 1280px (plus 600 to 1024px for the hint and nav). There is no horizontal scroll at any width. At 390px the diagram scrolls inside its box with the hint showing, and at 1280px it fits whole. Both tables fit at 390px. I looked at the screenshots.
• Not checked: the national cut's artefacts on the Hub, which are private, so I relied on #1284 for the certification claim. I didn't rebuild anything.

🤖 Generated with Claude Code

[juaristi22]

Thanks @vahid-ahmadi. bcef5aa (version 0.5) takes findings 1 to 5:

1. Which build the weighting describes: "Fitting with constraints" now opens "In the local build, the objective is shared equally among four groups…", adds "The national build gives each family of statistics an equal share", and says the ten-times limit applies in both builds. Reference [7] now also links national_doctrine.py.
2. Exact-size refit: the refit now says "with a penalty that keeps the weights close to equal". The size is named once, in the overview ("an exact-size selection of households (100,000 at this revision)"); the fitting and holdout paragraphs say "exact-size", so the move to 150,000 on main touches one place at the next re-pin. The 100,000 in the version 0.4 history entry stays, since it records that version.
3. Home values and bands: the value now comes from "HM Land Registry sale prices in its assigned constituency (the latest sale of each home since 1995, uprated with the UK House Price Index)", and the band from the VOA band mix for the copy's Lower Layer Super Output Area (LSOA).
4. Higher-rate small cells: the small-cell sentence now gives both rules: council-tax band cells of fewer than 50 dwellings, and higher-rate taxpayer cells below 5,500, which HMRC rounds to the nearest thousand.
5. High-value homes: "estimated by Microcosm from HM Land Registry sales and other published statistics", in the target table and in the diagram caption.
6. Nav wrap: we're keeping the nav link and accepting the wider two-row range, as the original PR intended. The walkthrough button and footer link are unchanged.

The changes you listed on main since 866fee4 (the 150,000 release size, the Chronicle re-pin, the withheld per-area support figures and Enhanced FRS 1.58.2) are left for the next re-pin, as you suggested. Code-owner enforcement still needs an admin to turn on branch protection for master.

[vahid-ahmadi]

@juaristi22 round 5, at 156ff44c1.

Verdict: not ready to merge yet. The method text holds against Microcosm at 90ff43f95, and everything from round 4 is in. Two new statements about certification go further than the evidence: the local-area file is not covered by the certificate, and no release can currently be built from 90ff43f95. Both are wording fixes. Not approving or merging; that stays with Vahid.

Round 4 (113ec9e), point by point

1. Which build the weighting describes: fixed. methodology/uk/index.html:345 opens "In the local build…", gives the national family_equal rule and says the 10x bound applies in both.
2. Exact-size refit penalty: fixed (:345). The size is named once (:101, now 150,000, matching UK_LOCAL_DATASET_HOUSEHOLDS, local_doctrine.py:212).
3. Home values and LSOA bands: fixed (:303).
4. Higher-rate small cells: fixed (:328).
5. High-value homes "and other published statistics": fixed (:324).
6. Nav wrap: kept on purpose, which is fine.

• Still open from earlier rounds, not blocking: master has no branch protection, so .github/CODEOWNERS isn't enforced (needs an admin); the contact is still the issues page (:388).

New findings

1. Must: the local-area file is not certified. :76 says "PolicyEngine certifies both files together", :249 says the local-area file "is certified together with the national file", and the v0.6 history (:391) repeats it.

   • policyengine.py says the opposite. docs/regions.md:112-113: "The certificate covers the national dataset only: receipts for runs on the local-area file are uncertified." The 6.10.0 changelog says the same, and tests/test_execution_receipt.py:415-429 asserts that a run on the local-area file is uncertified.
   • What is true: certification checks the local-area release's role, file and model claims and pins its bytes (regions.md:109-111), and 6.11.1 ships the two cuts as a pair (manifest.json:68-72,126).
   • Suggested: "Certification checks and pins the local-area file alongside the national file, but the certificate covers the national file only; results from the local-area file are recorded as uncertified."

2. Must: no release can currently be built from 90ff43f95, so the page shouldn't say one "is being built and certified" (:77).

   • 90ff43f95 includes #1381 (merged at f6a790cf0). Its draught shares are constant by construction, and uk_degenerate_release_surface (gates.json:928, terminal, release-blocking) refuses constant columns. degenerate_reviewed_exclusions.json at 90ff43f95 has no draught entry.
   • This happened today: the #1405 verification build stopped at the terminal gate on household.beer_draught_share and household.cider_draught_share. #1411 (open, draft) says "No release built since the step landed could pass it", and says the next pair is built from that branch, on policyengine-uk #2695, so not from 90ff43f95 and not with 2.162.8.
   • That also affects "from the next release" (:77, :285-286, :322-323). The alcohol, tobacco and gambling inputs (:286) are exactly what is blocking the release. As written, the page tells readers they will ship.
   • Suggested for :77: "This page describes the method at source revision 90ff43f95. No release has yet been certified from this revision or later; until one is, the release named above remains the one in use. Changes marked 'planned for the next release' reach users only if that release passes its checks." Then use "planned for the next release" at :285, :286, :322, :323.

3. Should: say the released files themselves aren't public (:388). The licence sentence is right that the microdata come from the UK Data Service and aren't redistributable. But the page now presents Microcosm UK as a certified dataset, and a reader may expect to download it. The cuts sit in policyengine/populace-uk-private (manifest.json:127). Suggested addition: "The released files are derived from these licensed surveys and are not publicly downloadable."

4. Nit: the policyengine.py version pins will go stale. :76 names 6.11.1, 67ee2ddf3 and 2.151.0. They're right today (CHANGELOG.md:1-5, manifest.json:22), but the next certification changes all three. "At the time of writing (27 October 2026)" already covers it. Just a reminder to update them at the next re-pin.

Claims I checked against Microcosm 90ff43f95 and policyengine.py 1e76104 (6.11.1)

• PolicyEngine-UK 2.162.8 is locked (uv.lock:1677-1678).
• 49 ordered stages (source_stages.json, 49 entries).
• 15 copies (local_doctrine.py:162), the 150,000-household selection (:212) and the 10x weight bound (:74).
• Release gates: ESS at least 1% of records (gates.json:972), max-to-median weight at most 100 (:1658), every row within 25% and half of each family of five or more (:1645-1650), and the ESS floor of 50 (local_doctrine.py:70).
• Holdout and Enhanced FRS comparison are optional for local releases (docs/uk-dense-release-assembly-runbook-762.md:23-28). A national release needs a passed rule-1 comparison with Enhanced FRS (docs/uk-national-release-assembly-runbook-806.md:73-77).
• Scotland's 18 BRMAs for rents and England's single-adult discount targets (local_targets.py:25,72-76).
• policyengine.py: 6.10.0 switched the UK default to Microcosm on 21 October and stopped loading the Enhanced FRS weight matrices. 6.11.1 serves the pair built at 67ee2ddf3 on 2.151.0.

Neutrality and disclosure

• The prose is neutral and quantitative, with no "poor" or "rich". The Enhanced FRS section (:352-355) still says the changes "do not, on their own, establish that every local estimate is more accurate".
• "In preparation" for the calibration paper is accurate: that page says "plan stage, no results".
• Numbers on the page are still only published figures, configuration constants or counts of geographies.
• Apart from findings 1 and 2, nothing overstates certification or accuracy.

Links, accessibility and layout

• All external links return 200 except the two expected 404s before merge (the canonical URL and tree/master/methodology).
• The new /support/paper, /calibration/paper and /sparsity/paper links return 200 on production. They 404 under python3 -m http.server only because that server doesn't do Vercel's cleanUrls.
• Every in-page anchor resolves.
• The heading order has no skipped levels (h1, then h2 and h3). There are no <img> tags. The SVG has <title> and <desc>, and the desc matches the new diagram.
• I rendered the page locally in headless Chrome with reduced motion at 1280px and 390px and looked at the screenshots. There's no horizontal page scroll at either width. Both tables fit at 390px (350 of 350px). At 390px the diagram scrolls inside its box, with the hint showing.

What I ran and didn't read

• The repo has no build step, tests, lint or CI workflow (static site, README:8-21), so there was nothing to run beyond serving it.
• I read the whole page and the diff bcef5aa11..156ff44c1. I didn't re-read the diagram SVG's coordinates line by line, only its rendering.
• I didn't rebuild any data, and I didn't open the private cuts on the Hub.

🤖 Generated with Claude Code

[juaristi22]

Thanks @vahid-ahmadi. Round 5 is addressed in b9b177a and 172921d.

1. Certification: we're keeping "certified" for both files. Certify the Microcosm UK pair on policyengine-uk 2.151.0 (a6299504 national, c9df4b86 local area) policyengine.py#720 certified the pair: certify-data ran on the national manifest and, through --regional-manifest-uri, on the local-area cut, so both files are checked and pinned in the bundle. Both also passed Microcosm's release checks at publication. The point of the wording is that both files get checked. Receipts for runs on the local-area file are still recorded as uncertified, as docs/regions.md says; the page doesn't go into receipts.
2. Next release: the status no longer says a release is being built from 90ff43f95. It now says the next release is being built on 90ff43f95 with policyengine-uk 2.162.12 and one unreleased engine change, without changing the method. It also says no release has yet been certified from this revision or later. The markers now read "planned for the next release", and the status says those changes reach users only if that release passes its checks.
3. Download: added "The released files are derived from these licensed surveys and are not publicly downloadable."
4. Version pins: noted. This PR stays pinned to 90ff43f95. Draft Re-pin the UK methodology to the next certified release (placeholder) #91 holds the re-pin to the next release, for when policyengine.py certifies it.

The earlier open items are unchanged: code-owner enforcement needs an admin, and the contact is still the issues page.

🤖 Generated with Claude Code

[vahid-ahmadi]

@juaristi22 round 6, at 172921d3e.

Verdict: not ready to merge yet. One must stays open (the local-area file's certification), and there is one new should. Not approving or merging; that stays with Vahid.

Round 5 items

1. must, the local-area file is not certified: still open. I take the point that certify-data --regional-manifest-uri checks and pins the local cut, and that it passed Microcosm's release checks. But those are two different things from policyengine.py's certificate:
   • policyengine.py #720's own check table puts the local file's "certified at publication" under the Microcosm release-cut gates row, and lists the national as "certified national-only".
   • docs/regions.md:112-113 on policyengine.py main (1e76104): "The certificate covers the national dataset only: receipts for runs on the local-area file are uncertified." The 6.10.0 changelog says the same.
   • On a public methodology page, "PolicyEngine certifies both files together" (methodology/uk/index.html:76) reads as "constituency and local-authority results are certified". policyengine.py records them as uncertified. :249 ("certified together with the national file") and the v0.6 line (:391) say the same.
   • Wording that keeps your point that both files are checked: "PolicyEngine certifies the national file. The local-area file is checked and pinned alongside it, and results from it are recorded as uncertified." Use it at :76, :249 and :391. We said the same on policyengine-model Progress page: re-bake inline snapshot to 2026-09-03 (forecast entry 22) #56 today, so the two sites should match.
2. must, "being built and certified": fixed. :77 now says no release has been certified from 90ff43f95 or later, and the markers read "planned for the next release" (:285, :286, :322, :323, :336). That is accurate today: microcosm #1411 is still an open draft, and policyengine.py main still serves the a6299504 national cut on 2.151.0 (manifest.json:37, :112).
3. should, files not public: fixed (:388).
4. nit, version pins: noted, with Re-pin the UK methodology to the next certified release (placeholder) #91 holding the re-pin.

New findings

1. should: say what the next release is built from (:77). "The next release is being built on this revision ... the method described here is unchanged" is right about the method. I read #1411's diff, and its stage code changes are version strings and comments only. But the pair is built from #1411's branch, not from 90ff43f95 as it stands. That branch adds signed exclusions for the two constant draught-share columns and for some gate-only target-fit rows in the local build. Those exclusions are why the earlier attempt failed and the rebuild can pass, and this page describes the release gates. Suggested: "The next release is being built from microcosm #1411, which adds to this revision signed exclusions for two constant draught-share columns and some gate-only target-fit rows, and PolicyEngine-UK 2.162.12 with one unreleased engine change."

What I ran

Fresh clone at 172921d3e. I read the diff 156ff44c1..172921d3e, every "certif" line on the page, #1411's description and diff, policyengine.py #720 and policyengine.py main's bundle manifest and docs/regions.md. I served the page with python3 -m http.server and took one headless Chromium screenshot at 1280 px, which I looked at; it renders as before. The repo has no build or tests to run.

🤖 Generated with Claude Code