Documentation audit — 2026-06-29

[claude]

Documentation Audit Report

Automated audit of docs/ and agent instruction files against source code and writing conventions.

Summary

Dimension	Findings
Freshness	2 gaps
Correctness	2 issues
Readability	0 issues

---

Freshness

Time window: 2026-06-15 to 2026-06-29 (14 days)
PRs reviewed: 8 | Doc-worthy: 2 | Gaps: 2

F-001: bin/mega-evme/AGENTS.md STRUCTURE missing lib.rs

• Priority: P2
• Source: PR feat(replay): self-validating fixtures + throughput benchmark (Rex5 mainnet, deploy registry) #306 feat(replay) feat(replay): self-validating fixtures + throughput benchmark (Rex5 mainnet, deploy registry) #306 — merged 2026-06-15
• What changed: Added bin/mega-evme/src/lib.rs holding all executable EVM logic, module re-exports, and set_thread_panic_hook(). main.rs became a thin CLI wrapper. bin/mega-evme/AGENTS.md not updated.
• Coverage: Not covered
• Target: bin/mega-evme/AGENTS.md STRUCTURE section
• What needs updating: Add src/lib.rs: Core CLI library — all executable logic, module re-exports, and panic hook. and change src/main.rs from "CLI bootstrap and panic hook" to "Thin CLI entry point — parses args and dispatches into lib.rs."

F-002: CLAUDE.md test organization missing tests/mutation/

• Priority: P2
• Source: PR ci: add cargo-mutants mutation-testing pipeline + limit-subsystem tests #325 ci: cargo-mutants pipeline ci: add cargo-mutants mutation-testing pipeline + limit-subsystem tests #325 — merged 2026-06-29
• What changed: Added crates/mega-evm/tests/mutation/ (6 modules: access_evm, block, constants, external_exec, limit, main). CLAUDE.md not updated.
• Coverage: Not covered
• Target: CLAUDE.md Test Organization section
• What needs updating: Add mutation/ to the directory list: "…rex5/, block_executor/, and mutation/ (mutation-killing integration tests for the limit/ subsystem)."

3 covered + 5 internal-only changes

Covered: PR #306 --dump-fixture → docs/mega-evme/commands/replay.md ✓ | PR #315 Rex5 doc sync → applied ✓ | PR #306 Rex5 mainnet timestamp → block/chain.rs (spec docs intentionally omit chain timestamps) ✓

Internal-only: #319 CI centralization | #318 skill fix | #317 version bump | #316 build-time verification | #313 perf optimization (all spec:unchanged)

---

Correctness

Scope: All docs/spec/ and docs/mega-evme/ pages + all agent files
Claims checked: ~60 | Verified: 58 | Stale: 2 | Incorrect: 0

C-001: bin/mega-evme/AGENTS.md — lib.rs missing; main.rs description stale

• Severity: Minor | Disposition: Stale
• Page: bin/mega-evme/AGENTS.md STRUCTURE section
• Doc says: `src/main.rs`: CLI bootstrap and panic hook. (no lib.rs entry)
• Source says: lib.rs holds all logic + set_thread_panic_hook(); main.rs is "a thin wrapper that only parses arguments and dispatches into this crate" (bin/mega-evme/src/lib.rs:4)
• Suggested correction: Add src/lib.rs entry; update src/main.rs to "Thin CLI entry point — parses args and dispatches into lib.rs."

C-002: CLAUDE.md test organization missing mutation/

• Severity: Minor | Disposition: Stale
• Page: CLAUDE.md Test Organization
• Doc says: "Tests are organized by spec: equivalence/, mini_rex/ (12 modules), rex/, rex2/, rex3/, rex4/, rex5/, and block_executor/."
• Source says: ls crates/mega-evm/tests/ includes mutation/ (added PR ci: add cargo-mutants mutation-testing pipeline + limit-subsystem tests #325)
• Suggested correction: Append , and mutation/(mutation-killing integration tests for thelimit/ subsystem).

Key verified claims

docs/spec/evm/dual-gas-model.md vs constants.rs: INTRINSIC_STORAGE_GAS=39,000 ✓, SSTORE_BASE=20,000 ✓, ACCOUNT_CREATION_BASE=25,000 ✓, CONTRACT_CREATION_BASE=32,000 ✓, CODE_DEPOSIT=10,000 ✓, LOG_TOPIC=3,750 ✓, LOG_DATA=80 ✓, calldata schedule (40/160/100/400) ✓.

docs/spec/evm/resource-limits.md vs constants.rs: TX_COMPUTE_GAS_LIMIT=200M ✓, TX/BLOCK_DATA_LIMIT=13,107,200 ✓, TX/BLOCK_KV_UPDATE_LIMIT=500,000 ✓, TX/BLOCK_STATE_GROWTH_LIMIT=1,000 ✓, FRAME numerator=98/denom=100 ✓.

docs/spec/evm/gas-detention.md vs constants.rs: BLOCK_ENV_CAP=20M ✓, BENEFICIARY_CAP=20M ✓, ORACLE_CAP=20M (Rex3+) ✓, historical 1M ✓.

CLAUDE.md agent claims: spec progression EQUIVALENCE→REX5 ✓, MiniRex1→EQUIVALENCE/MiniRex2→MINI_REX ✓, AdditionalLimit in limit/limit.rs ✓, block/chain.rs exports (hardfork_schedule, MAINNET_CHAIN_ID=4326, TESTNET_CHAIN_ID=6343, mainnet/testnet_hardforks) ✓, system contract addresses 0001–0006 ✓, STORAGE_CALL_STIPEND=23,000 ✓, Rex4 vs Rex5 stipend distinction ✓.

---

Readability

Scope: All docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md pages (agent files excluded)
Pages sampled: 7 | Pass: 7 | Fail: 0 | Total findings: 0

Category	Result
Structural Lint	Pass
Page Structure Compliance	Pass
Normative Language	Pass
Constants and Formulas	Pass
Spec Versioning	Pass
Cross-Linking	Pass
Formatting	Pass

Pages sampled: evm/dual-gas-model.md, evm/resource-limits.md, evm/gas-detention.md, evm/gas-forwarding.md, hardfork-spec.md, system-contracts/overview.md, upgrades/minirex.md. All pass: correct spec: Rex5 frontmatter, one-sentence-per-line markdown, RFC 2119 normative keywords in Specification/Security only, named constants in all formulas, proper spec-history cross-links. system-contracts/overview.md uses the lighter index-page structure (no Motivation/Rationale) per docs/spec/AGENTS.md conventions — correct.

[mega-putin]

1. Understanding: This issue is asking for a small documentation sync so the agent guidance matches the current code layout. The concrete updates are to document the mega-evme CLI split between lib.rs and main.rs, and to refresh the top-level test organization note if crates/mega-evm/tests/mutation/ is present on the target branch.

2. Approach:

• Update bin/mega-evme/AGENTS.md STRUCTURE to add src/lib.rs and rewrite the src/main.rs entry to reflect the current split.
• Use bin/mega-evme/src/lib.rs and bin/mega-evme/src/main.rs as the source of truth for the wording, since lib.rs now owns the executable logic and panic hook while main.rs is only the thin CLI entry point.
• Update CLAUDE.md Test Organization to include mutation/ with a short description, but only after verifying the directory exists in the branch being edited so the doc reflects the actual tree.
• Keep the edits minimal and consistent with repo markdown conventions, including one sentence per line if any prose needs to be reflowed.
• Run a quick verification pass with file listings / grep to confirm the updated claims match the repository structure after editing.

3. Risks:

• In the current checkout I inspected, crates/mega-evm/tests/mutation/ is not present, so that part of the issue appears to depend on a newer main state than this workspace currently has.
• If the local branch is behind main, the implementation should re-verify against the target branch before changing CLAUDE.md, otherwise we risk documenting a directory that is not actually in the tree.
• The scope is documentation-only, so the main human judgment is whether CLAUDE.md should describe the full test directory inventory or only the spec-oriented subsets.

Reply @mega-putin go to start implementation.