Constant-rename equivalence check: prove a rename changed no behaviour

A throwaway script written for PR #567 caught a real production-breaking
bug that git, the 3,036-test backend suite and the committed lint chain
all passed over. It lived only in a session scratchpad. This commits it.

The incident (2026-07-29): #567 renamed SLOW_PATH_TO_REVIEW_REASON to
SLOW_PATH_TO_REVIEW_SKIP_REASON; #568 concurrently added BRAND NEW code
in catalog_stats.py importing and using the OLD name. Git auto-merged
with no conflict - #568 only added lines, #567 only touched a nearby
docstring, so the rename and the new references never textually
collided. The merged result would have raised ImportError at
module-import time in a module reached by the catalog-stats view and the
hourly warm_catalog_stats job. Thirteen reference sites, six modules.
The generalisation: a textual merge cannot see a name graph.

1. .github/scripts/constant_rename_equivalence.py - two checks.
   --check-references (one revision, no judgment calls) resolves every
   matching constant reference: a `from x import NAME` where x declares
   no NAME is an ImportError, unconditionally. The equivalence check
   (two revisions) normalises each module at both - inlining matching
   constants with the map built across the WHOLE tree so cross-module
   imports resolve, deleting those declarations/__all__ entries/imports,
   deleting docstrings, constant-folding f-strings and string
   concatenation - then compares ast.dump() trees.

2. Generalised past skip reasons: --pattern is a regex searched against
   ALL-CAPS module-level names, defaulting to the families this repo
   actually refactors (SKIP_REASON|ANONYMOUS_ID|_VERSION|_WEIGHT|
   _THRESHOLD|_PREFIX|_REASON). --pattern '.' inlines everything.

3. Revisions are arguments; default is HEAD vs its merge-base with
   origin/master, with fallbacks so it works in a worktree with no
   remote. --paths narrows, --all widens.

4. Failures name the module, the AST node path, and both sides unparsed
   back to source - not "these trees differ" on a 2,000-line file.

5. Scope includes modules the diff never touched. A changed-files-only
   scope would have missed catalog_stats.py, which is the whole point:
   in the merge that broke, the rename half touched only
   local_calculate_verdicts.py.

CI wiring is deliberately two jobs with different trigger characters.
`references` is an unconditional invariant that runs on every Python PR
and can genuinely fail (same posture as protected-core-license).
`equivalence` gates ITSELF: with no renamed or removed constant in the
diff it prints "nothing to prove" and exits 0, rather than being a job
that runs always and passes always.

Tests follow test_docs_lint.py's conventions: fixture git repos, every
rule with a passing AND a failing case, including genuine behaviour
changes (a renamed constant whose value also moved; a comparison
operand change alongside a rename; a frozenset membership change), plus
a guard that a rename OUTSIDE the pattern is not normalised away. Two
real-repo tests pin the incident.

Two normaliser gaps were found and closed while running it against real
history, both real:
- matching had to widen to any name CONTAINING the pattern, because
  LANDS_PHASH_SKIP_REASON_PREFIX ends in _PREFIX, not _REASON;
- the f-string folder has to fold a SINGLE interpolated constant back
  into the surrounding literal, not just whole f-strings, because
  `f"phash-{r}"` and `f"{PREFIX}{r}"` are the same value in different
  shapes. Without this the real #567 commit reported a false difference.

Nothing was weakened to make the repo pass: the one remaining difference
reported against #567 is docs_lint.py, which that same PR legitimately
grew by 129 lines of new lint code.

Documented in docs/reference/constant-rename-equivalence.md (indexed
from docs/README.md and docs/MANIFEST.md), cross-referenced from
docs/reference/skip-reasons.md, promoted into docs/lessons.md per that
file's own triage ritual, and added to CLAUDE.md's task-end checks.

Verified: 37 unit tests pass; docs-lint --strict clean; pre-commit
clean; the tool reproduces the incident (6 ImportError findings plus 6
tree differences on a reconstructed auto-merge) and detects a
rename-plus-behaviour-change (7 modules, 'to-review' -> 'to-review-v2').

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN

Author: WilfordGrimley

.github/scripts/constant_rename_equivalence.py

@@ -0,0 +1,82 @@
+name: Constant-rename equivalence
+
+# Two checks over module-level constants, both from
+# .github/scripts/constant_rename_equivalence.py. Motivating incident and
+# full rationale: docs/reference/constant-rename-equivalence.md.
+#
+# PR #567 renamed SLOW_PATH_TO_REVIEW_REASON -> SLOW_PATH_TO_REVIEW_SKIP_REASON
+# while PR #568 concurrently added NEW code using the OLD name. Git
+# auto-merged with no conflict (#568 only added lines; #567 only touched a
+# nearby docstring), and the merged result would have raised ImportError at
+# module-import time in a module reached by the catalog-stats view and the
+# hourly warm_catalog_stats job. Neither branch was broken on its own — only
+# their merge was, which is precisely the revision a `pull_request` checkout
+# hands you.
+#
+# DELIBERATELY TWO JOBS, with different trigger characters:
+#
+#   `references` is an unconditional invariant. A matching constant imported
+#   from, or read in, a module that declares it nowhere is an ImportError or
+#   NameError, always, with no judgment call — so it runs on every Python PR
+#   and can genuinely fail. Same posture as protected-core-license: it passes
+#   with zero findings today, correctly, and exists to catch the day that
+#   stops being true.
+#
+#   `equivalence` is the expensive proof, and its natural trigger is a PR
+#   that RENAMES a constant, which is not most PRs. Rather than run always
+#   and pass always (which teaches people to ignore it), the script gates
+#   itself: with no renamed or removed constant in the diff it prints
+#   "nothing to prove" and exits 0. When it does fire, its output names the
+#   renamed constants and the exact differing AST node.
+#
+# Stdlib only — reads source text via `git cat-file`, never imports or
+# executes it, so no Django/third-party deps are needed in these jobs.
+
+on:
+  pull_request:
+    paths:
+      - "**/*.py"
+      - ".github/workflows/constant-rename-equivalence.yml"
+  push:
+    branches: ["master"]
+    paths:
+      - "**/*.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  references:
+    name: Every matching constant reference resolves
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Resolve every *_SKIP_REASON / *_ANONYMOUS_ID / threshold reference
+        run: python3 .github/scripts/constant_rename_equivalence.py --check-references
+
+  equivalence:
+    name: Renamed constants are behaviour-preserving
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Needs both sides of the comparison, and the merge-base.
+          fetch-depth: 0
+      - name: Prove the rename changed no behaviour
+        run: |
+          BASE="${{ github.event.pull_request.base.sha }}"
+          if [ -z "$BASE" ]; then BASE="$(git rev-parse HEAD~1)"; fi
+          python3 .github/scripts/constant_rename_equivalence.py --base "$BASE" --head HEAD
+
+  unit-tests:
+    name: constant_rename_equivalence.py unit tests
+    # Fixture git repos exercising each normalisation rule's passing AND
+    # failing case, plus real-repo regression pins for the #567 rename.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Run constant-rename equivalence unit tests
+        run: python3 .github/scripts/tests/test_constant_rename_equivalence.py

.github/scripts/tests/test_constant_rename_equivalence.py

@@ -70,6 +70,15 @@ not described here so it doesn't get re-derived.)
   by that doc's own mechanical tether in `docs_lint.py`, but only after the
   fact; get the judgment right at the row's creation instead of relying on
   CI to catch a wrong one later.
+- **Constant renames**: did this branch rename, extract, move or retire a
+  module-level constant (`*_SKIP_REASON`, `*_ANONYMOUS_ID`, a weight, a
+  threshold)? Run
+  `python3 .github/scripts/constant_rename_equivalence.py` before pushing.
+  It proves the touched modules normalise to identical ASTs once constants
+  are inlined, and separately resolves every matching reference — the check
+  that a clean textual auto-merge cannot do for you. Motivating incident and
+  limits:
+  [`docs/reference/constant-rename-equivalence.md`](docs/reference/constant-rename-equivalence.md).
 - **Push policy**: commit and push straight to `master` for solo work on
   this repo, no PR needed. PRs (+ user approval before merge) are reserved
   for upstreaming to `chilli-axe/mpc-autofill`. Never `git push --force` as

.github/workflows/constant-rename-equivalence.yml

@@ -34,6 +34,14 @@ The methodology and the systems it governs.
   declarations in code by `check_skip_reason_roster_tether()` in
   `.github/scripts/docs_lint.py`, on the same terms as the calculator
   roster: code is the source of truth, the doc is the thing checked.
+- [`reference/constant-rename-equivalence.md`](reference/constant-rename-equivalence.md)
+  — the AST-level check that proves a constant rename or extraction changed
+  no behaviour, and catches the concurrently-merged PR that silently breaks
+  one. Run it on any branch that renames a `*_SKIP_REASON`,
+  `*_ANONYMOUS_ID`, weight or threshold. Written up around the 2026-07-29
+  #567/#568 incident, where a clean textual auto-merge produced an
+  `ImportError` at module-import time that git, the 3,036-test backend
+  suite and the lint chain all passed over.
 - [`reference/vote-weight-matrix.md`](reference/vote-weight-matrix.md) —
   the owner-ratified 2026-07-22 vote-weight scenario matrix (raw decision
   record, implemented in PR #325) that `theory.md`'s §4/§7a and

CLAUDE.md

@@ -1023,3 +1023,28 @@ cards the broken gate already logged - they stay excluded forever. The fix has t
 `-vN` bump (family-keyed behaviour follows automatically via `models.calculator_family`), which
 makes "is this repair reachable by the population it is for?" a standing question for any Stage D
 predicate change, not an afterthought.
+
+## A clean textual auto-merge can still produce an unresolvable name — git, the test suite and mypy all agree, and all three are wrong
+
+A branch renamed `SLOW_PATH_TO_REVIEW_REASON` to `SLOW_PATH_TO_REVIEW_SKIP_REASON`. Concurrently,
+another branch added BRAND NEW code importing and using the OLD name. Git auto-merged with no
+conflict, and could not have done otherwise: one side only ADDED lines, the other only touched a
+nearby docstring, so the rename and the new references never textually collided. The merged
+result would have raised `ImportError: cannot import name 'SLOW_PATH_TO_REVIEW_REASON'` at
+module-**import** time, in a module reached by both a live view and an hourly scheduled job. The
+full backend suite passed on each branch, because **neither branch was broken** — only their
+merge was, and no CI job ran against that merge result with a checker that resolves names.
+
+The generalisation is the useful part: **a textual merge cannot see a name graph.** Two changes
+that never touch the same lines can still produce a tree in which a name no longer resolves, or
+resolves to a different value. Rename/extract/move refactors are the standing generator of this
+because they are exactly the changes whose diff is spread thinly over many files while carrying
+one indivisible semantic edit. Green CI on both branches is not evidence about the merge.
+
+Promoted to a gate, per this file's own triage ritual:
+[`reference/constant-rename-equivalence.md`](reference/constant-rename-equivalence.md) —
+`.github/scripts/constant_rename_equivalence.py` resolves every matching constant reference at
+the merge revision (which is what a `pull_request` checkout hands you), and, when a PR actually
+renames something, proves the touched modules normalise to identical ASTs once constants are
+inlined. Run it on any branch that renames a constant; do not weaken its normaliser to make a
+real repo pass — the one time a reported difference looked spurious, it was this bug.

docs/MANIFEST.md

@@ -0,0 +1,163 @@
+# Constant-rename equivalence check
+
+**What it is.** `.github/scripts/constant_rename_equivalence.py` — an
+AST-level checker that proves a constant-renaming or constant-extraction
+refactor changed no behaviour, and that catches the concurrent merge that
+silently breaks one.
+
+**When to run it.** Any time a branch renames, extracts, moves or retires a
+module-level constant — `*_SKIP_REASON`, `*_ANONYMOUS_ID`,
+`*_EXTRACTOR_VERSION`, a weight, a threshold. It runs itself in CI
+(`.github/workflows/constant-rename-equivalence.yml`), but the useful moment
+is before you push, on the branch, where the output is a two-line diff
+instead of a red check.
+
+```bash
+# HEAD vs its merge-base with origin/master
+python3 .github/scripts/constant_rename_equivalence.py
+
+# the name-resolution half alone: one revision, no diff needed
+python3 .github/scripts/constant_rename_equivalence.py --check-references
+```
+
+Exit code is the number of findings (0 = clean), matching
+`docs_lint.py`'s and `check_protected_core_license.py`'s convention.
+Stdlib only; it reads source text via `git cat-file` and never imports or
+executes it, so it needs no Django or third-party dependencies.
+
+## Why it exists — the #567/#568 incident, 2026-07-29
+
+PR #567 renamed `SLOW_PATH_TO_REVIEW_REASON` to
+`SLOW_PATH_TO_REVIEW_SKIP_REASON` in
+`MPCAutofill/cardpicker/local_calculate_verdicts.py`, as part of adopting
+the `*_SKIP_REASON` declaration convention that
+[`skip-reasons.md`](skip-reasons.md)'s roster tether depends on.
+
+Concurrently, PR #568 added **brand new** code in
+`MPCAutofill/cardpicker/catalog_stats.py` that imported and used the **old**
+name.
+
+Git auto-merged the two with **no conflict**. It could not have done
+otherwise: #568 only ADDED lines, and #567 only touched a nearby docstring,
+so the rename and the new references never textually collided. Nothing else
+caught it either — not the full backend suite (3,036 tests), and not the
+committed lint chain as it stood.
+
+The merged result would have raised, at module-**import** time:
+
+```
+ImportError: cannot import name 'SLOW_PATH_TO_REVIEW_REASON'
+```
+
+in a module imported by the catalog-stats view **and** by the hourly
+`warm_catalog_stats` job. Thirteen reference sites needed fixing across six
+modules. The throwaway script that found it was written for one PR and
+lived in a session scratchpad; this file is the version that does not get
+lost.
+
+The general shape of the defect: **a textual merge cannot see a name graph.**
+Two changes that never touch the same lines can still produce a tree in
+which a name no longer resolves, or resolves to a different value. Only
+something that resolves names across the whole tree at both revisions can
+tell.
+
+## What it checks
+
+Two independent checks, in increasing order of strength.
+
+### 1. References — one revision, no false positives
+
+Every `from x import NAME` whose NAME matches the pattern must actually be
+declared in `x`, and every matching ALL-CAPS name a module reads must
+resolve to a declaration somewhere in the tree. A violation is an
+`ImportError`/`NameError` waiting to happen, unconditionally — there is no
+judgment call and nothing to tune.
+
+This is the half that runs on **every** Python PR. Note that on a
+`pull_request` event, `actions/checkout` gives you the **merge result**, not
+the branch tip — which is exactly the revision the #567/#568 bug existed in
+and neither contributing branch did.
+
+### 2. Equivalence — two revisions
+
+For each module in scope, parse it at both revisions, then **normalise both
+sides** by:
+
+- inlining every module-level constant whose name matches the pattern, with
+  the constant map built across the **whole tree** at each revision, so a
+  cross-module `from x import Y_SKIP_REASON` resolves;
+- deleting those declarations, their `__all__` entries, and the imports that
+  only pulled them in;
+- deleting every docstring (prose is expected to change — in a rename PR it
+  is usually most of the diff);
+- constant-folding f-strings and string `+` concatenation;
+
+and comparing `ast.dump()` trees. **Identical trees mean every expression
+that used to evaluate to a given value still evaluates to the same value,
+under a different name.** A difference is reported with the module, the node
+path, and both sides rendered back to source:
+
+```
+::error file=MPCAutofill/cardpicker/catalog_stats.py::normalised trees differ at Module.body[21].body[7].value.keywords[1].value
+        9952865b: 'to-review'
+        90c34e3c: 'to-review-v2'
+```
+
+Scope is deliberately narrow: the modules that touch a constant whose
+declared **name** changed between the two revisions — which includes modules
+the diff never touched, and that is the point. `--all` widens it to every
+module mentioning the pattern; `--paths` narrows it to an explicit list.
+
+## The pattern is a parameter
+
+`--pattern` is a regex `re.search`-ed against ALL-CAPS module-level constant
+names. The default covers the families this repo actually refactors:
+
+```
+SKIP_REASON|ANONYMOUS_ID|_VERSION|_WEIGHT|_THRESHOLD|_PREFIX|_REASON
+```
+
+It is a `search`, not a suffix test, for a concrete reason:
+`LANDS_PHASH_SKIP_REASON_PREFIX` ends in `_PREFIX`, not `_REASON`, and its
+value is composed at runtime as `f"{PREFIX}{reason}"` — which is also why
+the f-string folder has to fold a _single interpolated constant_ back into
+the surrounding literal, not just whole f-strings. `--pattern '.'` inlines
+every ALL-CAPS module-level constant, the strongest and slowest setting.
+
+## Honest limits
+
+Stated plainly rather than discovered later:
+
+- The equivalence check is a proof about **pure** refactors. A PR that
+  renames a constant _and_ changes behaviour in the same modules will be
+  reported. That is correct, not a false positive: the tool cannot know the
+  behaviour change was intended, only that the refactor was not
+  behaviour-preserving. Split the PR, or read the reported node and land it
+  knowingly.
+- A matching constant that is declared but never referenced is deleted from
+  both sides by normalisation, so a change to _its_ value alone is invisible
+  to the tree comparison. Those are surfaced separately as informational
+  `note:` lines — not failures, because a legitimate constant-_extraction_
+  refactor moves the same multiset.
+- Declarations whose right-hand side is not a static expression (a call
+  outside the `frozenset`/`set`/`tuple`/`list`/`dict` allowlist, a
+  comprehension) are not inlined. They are listed as `note:` so you know
+  what the proof did **not** cover.
+- It reasons about names, not types or control flow. It is not a
+  replacement for mypy or the test suite; it covers a gap both of them have
+  demonstrably passed over.
+
+**Do not weaken the normaliser to make a real repo pass.** The one time a
+reported difference looked spurious, it was the production-breaking bug
+above. Investigate before excluding.
+
+## Tests
+
+`.github/scripts/tests/test_constant_rename_equivalence.py`, run by the same
+workflow and by `python3 .github/scripts/tests/test_constant_rename_equivalence.py`.
+Every rule has a passing and a failing case, including a genuine
+behaviour change (a renamed constant whose _value_ also moved) — a checker
+that only ever reports "identical" proves nothing. Two real-repo tests pin
+the incident: the committed tree resolves every matching reference, and the
+actual #567 commit still normalises identically against its parent across
+the twelve pipeline modules it touched.

docs/README.md

@@ -42,6 +42,16 @@ and `MPCAutofill/cardpicker/tests/test_skip_reason_roster.py` pins every
 declared value against an explicit expected set so a future rename cannot
 silently alter production data.
 
+That sweep is also where
+[`constant-rename-equivalence.md`](constant-rename-equivalence.md) came
+from: the rename half of it collided with a concurrently-merged PR that had
+added new code using an old constant name, and git auto-merged the two with
+no conflict into a tree that raised `ImportError` at module-import time.
+Run `.github/scripts/constant_rename_equivalence.py` on any branch that
+renames, extracts or retires a `*_SKIP_REASON` — the roster tether above
+checks that a value is DOCUMENTED, which is a different question from
+whether the code still resolves and still evaluates to the same string.
+
 ## How this doc is tethered
 
 `check_skip_reason_roster_tether()` in `.github/scripts/docs_lint.py`