refactor: replace abbreviated/vague locals with descriptive names (leanEthereum#837)

* refactor: replace abbreviated/vague locals with descriptive names

Rename `acc` accumulators in the XMSS base-P decomposition helpers to
names that say what they hold: `remaining_value` in field.py,
`message_integer`/`encoded_tweak` in encoding.py, and
`packed_lengths`/`packed_tweak` in poseidon.py. In `aborting_decode`,
expand the banned `fe`/`a`/`d` to `field_element`/`element_value`/`quotient`.

Also rename `description_count` to `descendant_count` in head_sync.py
since it counts processed descendant blocks, not descriptions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: default pull requests to the upstream main repository

Add a CLAUDE.md rule so PRs are opened against leanEthereum/leanSpec
(base main) by default rather than the personal fork, unless the user
explicitly requests otherwise.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tcoratger

CLAUDE.md

@@ -20,6 +20,7 @@ subspecifications that the Lean Ethereum protocol relies on.
 - Keep specs simple, readable, and clear
 - Repository is `leanSpec` not `lean-spec`
 - **Always run linter checks before finishing**: Run `just check` at the end of any code changes to ensure all linting, formatting, type checking, and spell checking passes.
+- **Pull requests target the main repo by default**: Unless the user explicitly says otherwise, open pull requests against the upstream main repository (`leanEthereum/leanSpec`, the `upstream` remote, base `main`) — NOT against a personal fork. Push the branch to the fork and open a cross-fork PR with `gh pr create --repo leanEthereum/leanSpec --base main --head <fork-owner>:<branch>`.
 - **CRITICAL - NO BACKWARD COMPATIBILITY**: This is a STRICT requirement. NEVER add backward compatibility code under any circumstances. This means:
   - NO legacy constants (like `KEY_TYPE_ED25519 = KeyType.ED25519`)
   - NO wrapper functions that delegate to new classes

src/lean_spec/node/sync/head_sync.py

@@ -300,11 +300,11 @@ async def _process_cached_descendants(
                     self.block_cache.remove(child_root)
 
                     # Recursively process this child's descendants.
-                    description_count, store = await self._process_cached_descendants(
+                    descendant_count, store = await self._process_cached_descendants(
                         parent_root=child_root,
                         store=store,
                     )
-                    processed_count += description_count
+                    processed_count += descendant_count
 
                 except Exception as exception:
                     # Processing failed. Leave in cache for retry or discard.

src/lean_spec/spec/crypto/xmss/encoding.py

@@ -60,8 +60,8 @@ def encode_message(config: XmssConfig, message: Bytes32) -> list[Fp]:
 
     The bytes are read little-endian as a single integer.
     """
-    acc = int.from_bytes(message, "little")
-    return int_to_base_p(acc, config.MESSAGE_LENGTH_FIELD_ELEMENTS)
+    message_integer = int.from_bytes(message, "little")
+    return int_to_base_p(message_integer, config.MESSAGE_LENGTH_FIELD_ELEMENTS)
 
 
 def encode_epoch(config: XmssConfig, epoch: Uint64) -> list[Fp]:
@@ -72,8 +72,8 @@ def encode_epoch(config: XmssConfig, epoch: Uint64) -> list[Fp]:
     # Layout:
     #
     #     (epoch << 8) | MESSAGE_PREFIX
-    acc = (int(epoch) << 8) | TWEAK_PREFIX_MESSAGE
-    return int_to_base_p(acc, config.TWEAK_LENGTH_FIELD_ELEMENTS)
+    encoded_tweak = (int(epoch) << 8) | TWEAK_PREFIX_MESSAGE
+    return int_to_base_p(encoded_tweak, config.TWEAK_LENGTH_FIELD_ELEMENTS)
 
 
 def aborting_decode(config: XmssConfig, field_elements: list[Fp]) -> list[int] | None:
@@ -90,18 +90,18 @@ def aborting_decode(config: XmssConfig, field_elements: list[Fp]) -> list[int] |
     threshold = config.Q * config.BASE**config.Z
 
     digits: list[int] = []
-    for fe in field_elements:
-        a = int(fe)
+    for field_element in field_elements:
+        element_value = int(field_element)
 
         # The only rejection case is A_i == P - 1.
-        if a >= threshold:
+        if element_value >= threshold:
             return None
 
         # Quotient by Q strips the residue.
         # The remainder is uniform in [0, BASE^Z - 1].
-        d = a // config.Q
+        quotient = element_value // config.Q
         for _ in range(config.Z):
-            d, digit = divmod(d, config.BASE)
+            quotient, digit = divmod(quotient, config.BASE)
             digits.append(digit)
 
     return digits[: config.DIMENSION]

src/lean_spec/spec/crypto/xmss/field.py

@@ -9,11 +9,11 @@
 
 def int_to_base_p(value: int, num_limbs: int) -> list[Fp]:
     """Decompose an integer into a fixed-size list of base-P field elements."""
-    acc = value
+    remaining_value = value
     limbs: list[Fp] = []
     for _ in range(num_limbs):
-        limbs.append(Fp(value=acc))
-        acc //= P
+        limbs.append(Fp(value=remaining_value))
+        remaining_value //= P
     return limbs
 
 

src/lean_spec/spec/crypto/xmss/poseidon.py

@@ -88,13 +88,13 @@ def safe_domain_separator(self, lengths: list[int], capacity_length: int) -> lis
             A capacity vector of length capacity_length.
         """
         # Pack all lengths into a single unambiguous integer using 32-bit slots.
-        acc = 0
+        packed_lengths = 0
         for length in lengths:
-            acc = (acc << 32) | length
+            packed_lengths = (packed_lengths << 32) | length
 
         # Compress the decomposed vector through the width-24 engine.
         # Width 24 is the only mode used for sponge domain separation.
-        input_vec = int_to_base_p(acc, 24)
+        input_vec = int_to_base_p(packed_lengths, 24)
         return self.compress(input_vec, 24, capacity_length)
 
     def sponge(
@@ -182,10 +182,12 @@ def tweak_hash(
         # Every other field sits in its own bit range above the prefix.
         match tweak:
             case TreeTweak(level=level, index=index):
-                acc = (level << 40) | (int(index) << 8) | TWEAK_PREFIX_TREE
+                packed_tweak = (level << 40) | (int(index) << 8) | TWEAK_PREFIX_TREE
             case ChainTweak(epoch=epoch, chain_index=chain_index, step=step):
-                acc = (int(epoch) << 24) | (chain_index << 16) | (step << 8) | TWEAK_PREFIX_CHAIN
-        encoded_tweak = int_to_base_p(acc, config.TWEAK_LENGTH_FIELD_ELEMENTS)
+                packed_tweak = (
+                    (int(epoch) << 24) | (chain_index << 16) | (step << 8) | TWEAK_PREFIX_CHAIN
+                )
+        encoded_tweak = int_to_base_p(packed_tweak, config.TWEAK_LENGTH_FIELD_ELEMENTS)
 
         if len(message_parts) == 1:
             # Hash chain step: width-16 compression of (digest || parameter || tweak).