From 8983070615b0812cb1c5aeae16e5de9e1b273d8f Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Sat, 26 Sep 2026 09:49:30 -0400 Subject: [PATCH 1/2] Require mirroring policy changes in Axiom RuleSpec Adds the axiom: PR-description line (encoded-correct | encoded | queued | n/a) and the dispatch-ready standard for queued rulespec issues. Co-Authored-By: Claude Opus 5.5 --- .github/CONTRIBUTING.md | 8 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 12 ++++++++++++ changelog.d/axiom-parity-guidelines.changed.md | 1 + docs/engineering/skills/github-prs.md | 16 ++++++++++++++++ 4 files changed, 37 insertions(+) create mode 100644 changelog.d/axiom-parity-guidelines.changed.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 24d8ad3289..cf17a663cc 100644 --- a/.github/CONTRIBUTING.md +++ b/.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-/`. 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. +- 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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e69de29bb2..453df24228 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,12 @@ +Fixes # + +## What and why + +## Test plan + +- [ ] YAML tests whose expected values come from an external source (legislation, official guidance, official calculator) +- [ ] `make format` +- [ ] Changelog fragment in `changelog.d/` + + +axiom: encoded-correct | encoded | queued | n/a: diff --git a/changelog.d/axiom-parity-guidelines.changed.md b/changelog.d/axiom-parity-guidelines.changed.md new file mode 100644 index 0000000000..519d89dc89 --- /dev/null +++ b/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. diff --git a/docs/engineering/skills/github-prs.md b/docs/engineering/skills/github-prs.md index 596438aeee..eadb157457 100644 --- a/docs/engineering/skills/github-prs.md +++ b/docs/engineering/skills/github-prs.md @@ -54,6 +54,22 @@ 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: encoded-correct | encoded | queued | n/a: +``` + +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: From af922472e8b222da9e840614c78e2817c5898695 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Sat, 3 Oct 2026 22:24:57 -0400 Subject: [PATCH 2/2] Allow axiom: queued only when the encoder is blocked; add axiom: needed Per the independent review: use queued only when the signed encoder is blocked, record the blocker in the issue, and require separate approval for each billed encoder run. The PR template and the github-prs skill also allow external contributors to write `axiom: needed`, and the template's YAML-test checkbox applies only to policy changes. Co-Authored-By: Claude Opus 5.5 --- .github/CONTRIBUTING.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- docs/engineering/skills/github-prs.md | 13 +++++++++---- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index cf17a663cc..77a63f217e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -52,7 +52,7 @@ Every policy change here must also be correct in [rulespec-uk](https://github.co - National modules live under `uk/`, and council schemes such as council tax reduction live under `uk-/`. 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. -- 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. +- 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 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 453df24228..efaaeeb295 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,9 +4,9 @@ Fixes # ## Test plan -- [ ] YAML tests whose expected values come from an external source (legislation, official guidance, official calculator) +- [ ] 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/` - + axiom: encoded-correct | encoded | queued | n/a: diff --git a/docs/engineering/skills/github-prs.md b/docs/engineering/skills/github-prs.md index eadb157457..a1ac512107 100644 --- a/docs/engineering/skills/github-prs.md +++ b/docs/engineering/skills/github-prs.md @@ -65,10 +65,15 @@ these applies in one line of the PR description: axiom: encoded-correct | encoded | queued | n/a: ``` -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"). +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