From 62b688d16c363ac91571e5108125d7c6e4c2a619 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Sat, 26 Sep 2026 09:49:20 -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 --- CONTRIBUTING.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f067d12..acfc161 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,9 +58,29 @@ Fragment `` drives the [SemVer](http://semver.org/) bump: - Body: layperson-readable explanation of *why* (motivation) and *what* (summary of changes). Include a test-plan checklist for non-trivial PRs. - Breaking changes: a separate "Migration" section with explicit before/after guidance. +## Mirror policy changes in Axiom + +PolicyEngine rules are also encoded as Axiom RuleSpec, in `TheAxiomFoundation/rulespec-` (for example [rulespec-us](https://github.com/TheAxiomFoundation/rulespec-us) and [rulespec-uk](https://github.com/TheAxiomFoundation/rulespec-uk)). Some country-model PRs change policy: a new program, a parameter or threshold update, an eligibility rule, a bug fix. Those PRs must also leave the same provision correct in the matching rulespec repo. Say how in one line of the PR description: + +```text +axiom: encoded-correct # an existing Axiom module already handles the case; cite the companion test that shows it +axiom: encoded # the provision was encoded or repaired alongside this PR +axiom: queued # a dispatch-ready encoding issue, labelled pe-parity +axiom: n/a: # infrastructure, data, UI, microsimulation-only or emulator-mapping changes +``` + +A `queued` issue must be ready for the encoder to run without further research: + +- the module path and corpus citation; +- the operative law, quoted verbatim; +- the required outputs; +- companion tests whose expected values come from the same external source as the PolicyEngine tests (statute, official form or worksheet, official calculator). + +[rulespec-us#1416](https://github.com/TheAxiomFoundation/rulespec-us/issues/1416) is an example. RuleSpec modules come from the signed encoder and are never written by hand. If you are an external contributor and can't do this, write `axiom: needed` and a maintainer will follow up. + ## Peer review -All PRs must be reviewed by someone other than the author. If no other reviewer is available, wait at least 24 hours from your last commit before self-review. Reviewers should look for tests, changelog fragment presence, and CI green status. +All PRs must be reviewed by someone other than the author. If no other reviewer is available, wait at least 24 hours from your last commit before self-review. Reviewers should look for tests, changelog fragment presence, CI green status, and an `axiom:` line on any PR that changes policy. ## Anti-patterns From 0a204d6d83029ec3e580830236686524793338a7 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Sat, 3 Oct 2026 22:24:56 -0400 Subject: [PATCH 2/2] Allow axiom: queued only when the signed encoder is blocked 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. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index acfc161..d04e828 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,11 +65,11 @@ PolicyEngine rules are also encoded as Axiom RuleSpec, in `TheAxiomFoundation/ru ```text axiom: encoded-correct # an existing Axiom module already handles the case; cite the companion test that shows it axiom: encoded # the provision was encoded or repaired alongside this PR -axiom: queued # a dispatch-ready encoding issue, labelled pe-parity +axiom: queued # the signed encoder is blocked; a dispatch-ready encoding issue, labelled pe-parity axiom: n/a: # infrastructure, data, UI, microsimulation-only or emulator-mapping changes ``` -A `queued` issue must be ready for the encoder to run without further research: +Use `queued` only when the signed encoder is blocked; record the blocker in the issue. Each billed encoder run requires separate approval. A `queued` issue must be ready for the encoder to run without further research: - the module path and corpus citation; - the operative law, quoted verbatim;