Require mirroring policy changes in Axiom RuleSpec

.github/CONTRIBUTING.md

@@ -46,6 +46,14 @@ and add `verified_end_year` when verified coverage has a defined end. Change the
 verified year fields only after confirming that parameters and tests cover the
 stated years.
 
+## Axiom parity
+
+Every policy change here must also be correct in [rulespec-uk](https://github.com/TheAxiomFoundation/rulespec-uk). That covers a new programme, a parameter or threshold update, an eligibility rule and a bug fix. The shared guide, [Mirror policy changes in Axiom](https://github.com/PolicyEngine/.github/blob/main/CONTRIBUTING.md#mirror-policy-changes-in-axiom), defines the `axiom:` line your PR description needs and what a `queued` issue must contain. UK specifics:
+
+- National modules live under `uk/`, and council schemes such as council tax reduction live under `uk-<council>/`. Search `main` there before opening a new issue.
+- An `encoded-correct` claim names the module and a companion case in its `.test.yaml` that exercises the same situation as your YAML test.
+- Use `queued` only when the signed encoder is blocked; record the blocker in the issue. Each billed encoder run requires separate approval. Label `queued` issues `pe-parity`. Reuse your YAML test's externally sourced expected values (legislation.gov.uk, gov.uk guidance, official calculators) as the companion tests; don't copy values computed by policyengine-uk.
+
 ## Repo-specific anti-patterns
 
 - **Don't change HF upload destinations** in the `policyengine-uk-data` upload pipeline without explicit authorisation — the private/public split exists to respect the UK Data Service licence.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+Fixes #
+
+## What and why
+
+## Test plan
+
+- [ ] For policy changes: YAML tests whose expected values come from an external source (legislation, official guidance, official calculator); otherwise mark not applicable.
+- [ ] `make format`
+- [ ] Changelog fragment in `changelog.d/`
+
+<!-- Required for any change to policy (programmes, parameters, eligibility, bug fixes). See .github/CONTRIBUTING.md ("Axiom parity"). Keep one standard option below, or use axiom: needed if you are an external contributor who cannot complete the Axiom work; a maintainer will follow up. -->
+axiom: <legal id> encoded-correct | <rulespec-uk PR> encoded | <rulespec-uk issue> queued | n/a: <reason>

changelog.d/axiom-parity-guidelines.changed.md

@@ -0,0 +1 @@
+- Documented that policy changes must be mirrored in Axiom RuleSpec (rulespec-uk), and added a pull request template with the required `axiom:` line.

docs/engineering/skills/github-prs.md

@@ -54,6 +54,27 @@ unless the user or maintainer explicitly asks. The type controls the inferred
 version bump: `breaking` is major, `added` and `removed` are minor, and other
 types are patch.
 
+## Required Axiom Line
+
+Every PR that adds, updates or fixes policy (programmes, parameters, eligibility
+rules, bug fixes) must also leave the same provision correct in
+[rulespec-uk](https://github.com/TheAxiomFoundation/rulespec-uk). State which of
+these applies in one line of the PR description:
+
+```text
+axiom: <legal id> encoded-correct | <rulespec-uk PR> encoded | <rulespec-uk issue> queued | n/a: <reason>
+```
+
+If you are an external contributor and cannot complete the Axiom work, use
+`axiom: needed`; a maintainer will follow up.
+
+Use `queued` only when the signed encoder is blocked; record the blocker in the
+issue. Each billed encoder run requires separate approval. A `queued`
+rulespec-uk issue must be dispatch-ready and labelled `pe-parity`. It needs the
+module path and corpus citation, the verbatim law, the required outputs, and
+companion tests from the same external source as the PR's YAML tests. Never
+hand-write RuleSpec. See `.github/CONTRIBUTING.md` ("Axiom parity").
+
 ## Required Lint And Format
 
 Run lint and formatting before committing. The default command is: