Add a rules registry that makes every enforced and unenforced rule visible

[anth-volk]

Fixes #751

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

Stacked PR. This is the middle of a native GitHub stack: Phase 0 (#754) → this PR → steps 1.3, 1.5 and 1.6 (#757). It's based on phase-0-enforcement and was rebased onto it, so the diff shows only this layer.

• Adds rules/registry.toml: every rule that governs this repository, with its tier (mechanical, metric or judgment), status (enforced, ratcheted, advisory or doc-only), enforcer, and the CI job that runs it. 38 rules, of which 13 are doc-only gaps, for example the gateway/executor import boundary and the observability rules. After Phase 0, the image-smoke and test-matrix rules describe the fixed state; nothing enforces them yet. Phase 0's explicit ruff rule list is registered as an advisory lint rule. Code-owned rule machinery and the agent no-bypass rule are registered as doc-only until branch rules enforce them.

• Adds scripts/rules/, a standard-library tool with validate, render and guard commands. The guard fails when:

  • an enforcer doesn't exist;
  • a CI job doesn't run the enforcer it claims to;
  • a guard test, quality guard or CI job isn't registered;
  • a proof test isn't collected by any CI job;
  • a baseline grows relative to the base branch;
  • an exception or review_by date expires;
  • the rendered views are stale.

  The tool is byte-identical with the same directory in policyengine-api; see scripts/rules/SYNC.md.

• Renders docs/generated/rules.md (a summary, a Gaps section, and a per-category table with Mermaid graphs), and a generated Rules block in AGENTS.md.

• Adds scripts/run_quality_guards.py and a dependency-free quality-guards PR job. The job runs the tool's unittest suite and the guards, with fetch-depth: 0 so baselines can be compared with the base branch.

• Adds a proof fixture and test for sim.stage12.no-schema-ddl, showing the DDL check rejects a bad example and accepts a good one.

• Documents how to add or change a rule in docs/engineering/skills/rules-registry.md.

Ruff rules are never ratcheted: adopting a ruff family is one standalone PR that fixes every violation.

Testing

• python -m unittest discover -s scripts/rules/tests -t .: 54 tests pass. The first version, with 50, was run on Python 3.11 to 3.14; the 4 added since cover proof tests that must run in CI.
• python scripts/run_quality_guards.py: rules-registry: passed.
• python -m scripts.rules guard --base-ref origin/main: passes. The base has no registry yet, so the baseline comparison is skipped.
• projects/policyengine-simulation-entry: uv run pytest tests/ passes (159 tests, including the new proof test).
• libs/policyengine-stage12-persistence: uv run pytest tests/ passes (12 tests).
• ruff format --check passes on all src directories and the new files.
• Each of these negative checks failed the guard as expected and was then reverted:
  • removing a deployment test from a rule;
  • adding an unregistered GUARDS entry;
  • hand-editing the AGENTS block;
  • changing a job invocation to a nonsense value;
  • adding an expired exception;
  • adding a baseline to a ruff rule;
  • removing a project from the test matrix.

🤖 Generated with Claude Code