Fix intervals per slot in CLAUDE.md from 4 to 5

[pablodeymo]

Motivation

A spec-to-code compliance audit (FINDING-006) identified stale documentation in CLAUDE.md. The spec (config.py INTERVALS_PER_SLOT=5) and the Rust code (lib.rs:35) both use 5 intervals per slot, but CLAUDE.md documented only 4 with incorrect interval descriptions.

Description

Updates two sections in CLAUDE.md:

Tick-Based Validator Duties — fixes the header from "4 intervals per slot" to "5 intervals per slot" and corrects the interval descriptions to match the actual implementation:

Interval	Old (incorrect)	New (correct)
0	Proposer check → accept attestations → build/publish block	Block proposal → accept attestations if proposal exists
1	Non-proposers produce attestations	Vote propagation (no action)
2	Safe target update (fork choice with 2/3 threshold)	Aggregation (aggregators create proofs from gossip signatures)
3	Accept accumulated attestations	Safe target update (fork choice)
4	(missing)	Accept accumulated attestations

Attestation Pipeline — fixes the interval reference from "intervals 0/3" to "intervals 0/4" for attestation promotion.

How to Test

Documentation-only change.

[github-actions]

🤖 Kimi Code Review

Looking at this PR diff, I need to review the changes to the validator duty timing documentation in CLAUDE.md.

Review Summary

The changes update the tick-based validator duty intervals from 4 to 5 intervals per 4-second slot. This is a documentation-only change, but it's critical for consensus correctness.

Issues Found

1. Inconsistency in Interval 0 Description

File: CLAUDE.md, line 48-49
Issue: The new description says "Block proposal → accept attestations if proposal exists" but this is ambiguous. The original "Proposer check → accept attestations → build/publish block" was clearer about the sequence.

Suggestion: Clarify the exact sequence. Does the proposer check happen first? When exactly is the block built and published?

2. Missing Context for Interval 1

File: CLAUDE.md, line 50
Issue: "Vote propagation (no action)" is unclear. If there's no action, why is this a separate interval?

Suggestion: Either explain what passive vote propagation means, or clarify why this interval exists.

3. Aggregation Timing Concern

File: CLAUDE.md, line 51
Issue: Moving aggregation to interval 2 might be too early. In typical Ethereum consensus, aggregation happens after attestation collection.

Suggestion: Verify this timing aligns with the actual implementation. Interval 2 might be too early for meaningful aggregation.

4. Attestation Pipeline Update

File: CLAUDE.md, line 58
Issue: The attestation pipeline comment says "↓ (intervals 0/4)" but interval 0 is for block proposal, not attestation processing.

Suggestion: Update to "↓ (interval 4)" only, as interval 0 is primarily for block proposal.

Positive Aspects

• The change from 4 to 5 intervals provides better granularity
• The separation of aggregation (interval 2) from safe target update (interval 3) is good architectural separation
• The documentation structure remains clear and consistent

---

Automated review by Kimi (Moonshot AI) · custom prompt

[github-actions]

🤖 Codex Code Review

No code-level findings in this PR.

• The diff only changes documentation in CLAUDE.md:48, CLAUDE.md:50, and CLAUDE.md:60.
• There are no Rust code changes, so there is no direct impact on fork choice correctness, attestation validation, state transition logic, XMSS verification, SSZ handling, memory safety, or runtime performance.

Residual risk / gap:

1. Confirm implementation and tests actually use 5 duty intervals and promotion at intervals 0/4 as documented, to avoid doc/runtime drift (same references above).

---

Automated review by OpenAI Codex · custom prompt

[github-actions]

🤖 Claude Code Review

PR 219 Review: Fix intervals per slot in CLAUDE.md from 4 to 5

Scope: Documentation-only change to CLAUDE.md.

---

Correctness Verification

I cross-checked every change against the live implementation:

INTERVALS_PER_SLOT = 5 — confirmed at crates/blockchain/src/lib.rs:35:

pub const INTERVALS_PER_SLOT: u64 = 5;

Interval descriptions — confirmed against the match interval block in crates/blockchain/src/store.rs:322-346:

Interval	New CLAUDE.md	Code
0	Block proposal → accept attestations if proposal exists	accept_new_attestations(store, false) if proposal ✓
1	Vote propagation (no action)	// Vote propagation — no action ✓
2	Aggregation (aggregators create proofs from gossip signatures)	aggregate_committee_signatures(store) ✓
3	Safe target update (fork choice)	update_safe_target(store) ✓
4	Accept accumulated attestations	accept_new_attestations(store, true) ✓

Attestation Pipeline intervals 0/3 → 0/4 — confirmed at lib.rs:144:

// head may change when attestations are promoted at intervals 0/4

---

Assessment

All changes are accurate and properly supported by the implementation. The PR description is thorough, including a clear table mapping old vs. new descriptions. No issues found.

Approved — clean, correct documentation fix.

---

Automated review by Claude (Anthropic) · custom prompt

[greptile-apps]

Greptile Summary

This PR fixes stale documentation in CLAUDE.md where the tick-based validator duties section incorrectly listed 4 intervals per slot (instead of 5) with outdated interval descriptions, and the attestation pipeline incorrectly referenced "intervals 0/3" instead of "intervals 0/4". The corrections are well-grounded: INTERVALS_PER_SLOT = 5 in lib.rs:35, the interval match arms in store.rs:322-346 confirm the new descriptions for intervals 0, 2, 3, and 4, and lib.rs:144 confirms the "0/4" attestation promotion note.

• ✅ "5 intervals per slot" now matches INTERVALS_PER_SLOT = 5 (lib.rs:35)
• ✅ Interval 0 description accurately reflects both block proposal (lib.rs) and conditional attestation acceptance (store.rs)
• ⚠️ Interval 1 description changed from "Non-proposers produce attestations" to "Vote propagation (no action)" — the latter matches only the store's empty match arm; lib.rs:137-140 still actively calls produce_attestations at interval 1, so the description may mislead readers
• ✅ Intervals 2, 3, 4 descriptions accurately match store.rs
• ✅ Attestation pipeline "intervals 0/4" matches the comment at lib.rs:144

Confidence Score: 4/5

• Safe to merge — documentation-only change with no runtime impact; the core fixes are correct.
• All substantive facts (interval count, intervals 2–4, attestation pipeline reference) are verified against the implementation. The only concern is that the new Interval 1 description ("Vote propagation (no action)") loses accuracy by omitting that produce_attestations is still called there in lib.rs, potentially misleading future developers.
• No files require special attention; the single file changed is CLAUDE.md (documentation only).

Important Files Changed

Filename	Overview
CLAUDE.md	Documentation-only change: fixes interval count (4→5) and descriptions to match actual implementation in store.rs and lib.rs, and corrects the attestation pipeline interval reference (0/3→0/4). Interval 1 description is slightly ambiguous.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    T[Tick Event] --> CALC[Calculate slot & interval]
    CALC --> I0{Interval 0}
    CALC --> I1{Interval 1}
    CALC --> I2{Interval 2}
    CALC --> I3{Interval 3}
    CALC --> I4{Interval 4}

    I0 -->|has_proposal?| ACC0[accept_new_attestations\nstore.rs]
    I0 --> PROP[propose_block\nlib.rs]

    I1 --> ATTEST[produce_attestations\nlib.rs\nnon-proposers sign + gossip]

    I2 -->|is_aggregator?| AGG[aggregate_committee_signatures\nstore.rs]

    I3 --> SAFE[update_safe_target\nstore.rs]

    I4 --> ACC4[accept_new_attestations\nlog fork-choice tree\nstore.rs]

    ACC0 --> HEAD[update_head]
    ACC4 --> HEAD

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: CLAUDE.md
Line: 51

Comment:
**Interval 1 description loses accuracy**

The new description "Vote propagation (no action)" matches only the *store's* perspective — `store.rs` has an empty match arm for interval 1 with that exact comment. However, `lib.rs:137-140` shows that `BlockChainServer::on_tick` **does** actively call `produce_attestations(slot)` at interval 1, signing and publishing attestations to the gossip network for all non-proposer validators.

The previous wording — "Non-proposers produce attestations" — more accurately described the overall system behavior at this interval. Saying "(no action)" risks misleading developers into thinking nothing happens at interval 1.

Consider a description that captures both layers:

```suggestion
Interval 1: Vote propagation (non-proposers produce and gossip attestations)
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 662ca2f}