fix(testing): make finalized-safety head check scheme-independent

[tcoratger]

Problem

test_fork_above_finalized_wins_at_or_below_loses passed under the test scheme but failed under prod:

AssertionError: Step 5: head_slot = 6, expected 5

Root cause — a scheme-dependent fork-choice tie

At step 5 the test adds above_6 (slot 6) as a sibling of block_5 (slot 5) — both children of the justified block block_4, both empty (no attestations target either).

• LMD-GHOST starts the head walk at the justified root block_4 and takes the heaviest child. Every chain vote (V0..V5) has latest-message head = block_4, so neither child gets distinguishing weight → a zero-weight tie.
• The spec breaks weight ties by block root (standard LMD-GHOST), fork_choice.py:

  head = max(children, key=lambda child_root: (weights[child_root], child_root))

• A block root is hash_tree_root(Block), which includes the state_root, which embeds the validator registry → each validator's XMSS public key. test and prod use different XMSS schemes, so the keys differ → state_root differs → the two block roots differ, and their ordering flips:
  • test keys: root(block_5) > root(above_6) → head block_5 (slot 5) ✅
  • prod keys: root(above_6) > root(block_5) → head above_6 (slot 6) ❌

So the test asserted the outcome of a hash-based tiebreak that happens to depend on key material. The spec is correct; the test expectation was scheme-fragile.

(The sibling test in the same file does not fail because its fork branches off block_1, below the justified root, so it is unreachable in the head walk — block_5 is the sole reachable child, no tie.)

Fix

At the tie step, stop asserting which sibling is head. Assert instead the scheme-independent facts that the empty fork block changes neither justification (block_4) nor finalization (block_3). The genuine "above fork wins" behavior is still asserted deterministically at the next step, where above_7 brings the 6 votes that justify above_6 and move the head onto above_7 (whose parent has a single child → no tie).

The test's Given/When/Then docstring describes the final state and reachability — both scheme-independent — and never asserted the step-5 head, so it stays accurate unchanged.

Also

Adds a repository rule to CLAUDE.md: every test change must update the associated documentation in the same change, per the documentation rules (with the tests/consensus/ step ↔ Given/When/Then mapping kept one-to-one).

Testing

• just check passes.
• Both tests in the file pass under the test scheme (no regression).
• The fix removes the only scheme-dependent assertion, so it holds under prod (where the step-5 head is legitimately above_6).

🤖 Generated with Claude Code