Documentation Audit Report
Automated audit of docs/ against source code and writing conventions.
Summary
| Dimension |
Findings |
| Freshness |
0 gaps |
| Correctness |
7 issues |
| Readability |
14 issues |
Freshness
Time window 2026-05-11 to 2026-05-25. PRs reviewed: 6. Coverage gaps: 0.
#284 (CALLCODE storage gas fix) is covered in docs/spec/hardfork-spec.md and docs/spec/upgrades/rex5.md. PRs 293-298 are internal fixes/perf with no spec behavior change.
Correctness
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md, plus agent files.
Claims checked: 71 | Verified: 63 | Issues: 7
C-001 Major docs/spec/evm/overview.md misattributes 98/100 gas forwarding rule to Rex. Source docs/spec/evm/gas-forwarding.md:56-57 shows MiniRex introduced it for CALL/CREATE/CREATE2; Rex extended to all CALL-like opcodes. Fix: update attribution.
C-002 Blocker docs/mega-evme/commands/run.md:65,300, docs/mega-evme/commands/tx.md:205, docs/mega-evme/configuration/chain-and-spec.md:15 show Rex4 as default spec. Source bin/mega-evme/src/common/env.rs:30-32 sets default_value=Rex5. Fix: update all three pages and help-output blocks to show Rex5 as default.
C-003 Major docs/mega-evme/commands/replay.md says default hardfork config is currently equivalent to Rex4. Source bin/mega-evme/src/replay/hardforks.rs:29-39 activates Rex5 at Timestamp(0). Fix: change to Rex5 or remove parenthetical.
C-004 Major docs/mega-evme/configuration/chain-and-spec.md available-specs table ends at Rex4. Source crates/mega-evm/src/evm/spec.rs:48 and bin/mega-evme/src/common/env.rs:31 include Rex5. Fix: add Rex5 row.
C-005 Minor bin/mega-evme/AGENTS.md STRUCTURE omits src/hasher/. Source bin/mega-evme/src/lib.rs:14-15 declares pub mod hasher and directory exists. Fix: add entry.
C-006 Major docs/mega-evme/commands/run.md:300 and docs/mega-evme/commands/tx.md:205 help-text blocks list specs to Rex4. Covered by C-002 fix.
C-007 Minor (ambiguous) docs/mega-evme/ has no Rex5 documentation. Rex5 is current default per bin/mega-evme/src/common/env.rs:31-32 but may be intentionally absent during unstable period. Fix: add note if intentional, otherwise covered by C-002/C-004.
Readability
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md (45 pages).
Findings: 14 (3 blocker, 4 major, 7 minor)
R-001 Blocker docs/spec/upgrades/rex5.md:88-101 New behavior prose references internal function names (interpreter.input.target_address(), new_account_storage_gas(), target_updated flag). Fix: rewrite as observable behavior.
R-002 Blocker docs/spec/upgrades/minirex.md:169 contains developer advice (Front-load volatile reads and minimize computation after access.) prohibited in spec pages. Fix: remove.
R-003 Blocker docs/spec/upgrades/rex5.md:77 uses MUST in informative upgrade page. Fix: rewrite without normative keyword.
R-004 Major docs/spec/evm/gas-forwarding.md:56-57 subsection Opcode Scope by Spec Version inside Specification section names MiniRex and Rex explicitly. Fix: move into Spec History or Rationale.
R-005 Major docs/spec/system-contracts/overview.md missing Motivation, Rationale, and Security Considerations. Fix: add all three.
R-006 Major docs/spec/upgrades/rex5.md:7, docs/spec/hardfork-spec.md:117, docs/spec/system-contracts/sequencer-registry.md:8, docs/spec/system-contracts/overview.md:37 use bare blockquote for unstable warnings instead of GitBook hint block. Fix: replace with hint style=warning / endhint block.
R-007 Major docs/spec/system-contracts/sequencer-registry.md entire body describes Rex5 without a details wrapper; other pages use details blocks for unstable content. Fix: wrap in details labeled Rex5 (unstable) and set spec frontmatter to Rex4, or add AGENTS.md exemption.
R-008 Minor docs/spec/evm/resource-accounting.md:230 mentions target_updated flag (internal mechanics). Fix: rewrite as behavioral description.
R-009 Minor docs/spec/system-contracts/sequencer-registry.md missing Security Considerations (rex5_initial_admin lockout, admin transfer, applyPendingChanges gas).
R-010 Minor docs/spec/system-contracts/high-precision-timestamp.md missing Security Considerations.
R-011 Minor docs/spec/system-contracts/mega-access-control.md and mega-limit-control.md missing Security Considerations.
R-012 Minor docs/spec/evm/dual-gas-model.md:16,18 multi-sentence lines. Fix: one sentence per line.
R-013 Minor docs/spec/hardfork-spec.md:15-16,122 multi-sentence lines. Fix: one sentence per line.
R-014 Minor docs/spec/overview.md:65 multi-sentence line. Fix: break or consolidate.
Documentation Audit Report
Automated audit of docs/ against source code and writing conventions.
Summary
Freshness
Time window 2026-05-11 to 2026-05-25. PRs reviewed: 6. Coverage gaps: 0.
#284 (CALLCODE storage gas fix) is covered in docs/spec/hardfork-spec.md and docs/spec/upgrades/rex5.md. PRs 293-298 are internal fixes/perf with no spec behavior change.
Correctness
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md, plus agent files.
Claims checked: 71 | Verified: 63 | Issues: 7
C-001 Major docs/spec/evm/overview.md misattributes 98/100 gas forwarding rule to Rex. Source docs/spec/evm/gas-forwarding.md:56-57 shows MiniRex introduced it for CALL/CREATE/CREATE2; Rex extended to all CALL-like opcodes. Fix: update attribution.
C-002 Blocker docs/mega-evme/commands/run.md:65,300, docs/mega-evme/commands/tx.md:205, docs/mega-evme/configuration/chain-and-spec.md:15 show Rex4 as default spec. Source bin/mega-evme/src/common/env.rs:30-32 sets default_value=Rex5. Fix: update all three pages and help-output blocks to show Rex5 as default.
C-003 Major docs/mega-evme/commands/replay.md says default hardfork config is currently equivalent to Rex4. Source bin/mega-evme/src/replay/hardforks.rs:29-39 activates Rex5 at Timestamp(0). Fix: change to Rex5 or remove parenthetical.
C-004 Major docs/mega-evme/configuration/chain-and-spec.md available-specs table ends at Rex4. Source crates/mega-evm/src/evm/spec.rs:48 and bin/mega-evme/src/common/env.rs:31 include Rex5. Fix: add Rex5 row.
C-005 Minor bin/mega-evme/AGENTS.md STRUCTURE omits src/hasher/. Source bin/mega-evme/src/lib.rs:14-15 declares pub mod hasher and directory exists. Fix: add entry.
C-006 Major docs/mega-evme/commands/run.md:300 and docs/mega-evme/commands/tx.md:205 help-text blocks list specs to Rex4. Covered by C-002 fix.
C-007 Minor (ambiguous) docs/mega-evme/ has no Rex5 documentation. Rex5 is current default per bin/mega-evme/src/common/env.rs:31-32 but may be intentionally absent during unstable period. Fix: add note if intentional, otherwise covered by C-002/C-004.
Readability
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md (45 pages).
Findings: 14 (3 blocker, 4 major, 7 minor)
R-001 Blocker docs/spec/upgrades/rex5.md:88-101 New behavior prose references internal function names (interpreter.input.target_address(), new_account_storage_gas(), target_updated flag). Fix: rewrite as observable behavior.
R-002 Blocker docs/spec/upgrades/minirex.md:169 contains developer advice (Front-load volatile reads and minimize computation after access.) prohibited in spec pages. Fix: remove.
R-003 Blocker docs/spec/upgrades/rex5.md:77 uses MUST in informative upgrade page. Fix: rewrite without normative keyword.
R-004 Major docs/spec/evm/gas-forwarding.md:56-57 subsection Opcode Scope by Spec Version inside Specification section names MiniRex and Rex explicitly. Fix: move into Spec History or Rationale.
R-005 Major docs/spec/system-contracts/overview.md missing Motivation, Rationale, and Security Considerations. Fix: add all three.
R-006 Major docs/spec/upgrades/rex5.md:7, docs/spec/hardfork-spec.md:117, docs/spec/system-contracts/sequencer-registry.md:8, docs/spec/system-contracts/overview.md:37 use bare blockquote for unstable warnings instead of GitBook hint block. Fix: replace with hint style=warning / endhint block.
R-007 Major docs/spec/system-contracts/sequencer-registry.md entire body describes Rex5 without a details wrapper; other pages use details blocks for unstable content. Fix: wrap in details labeled Rex5 (unstable) and set spec frontmatter to Rex4, or add AGENTS.md exemption.
R-008 Minor docs/spec/evm/resource-accounting.md:230 mentions target_updated flag (internal mechanics). Fix: rewrite as behavioral description.
R-009 Minor docs/spec/system-contracts/sequencer-registry.md missing Security Considerations (rex5_initial_admin lockout, admin transfer, applyPendingChanges gas).
R-010 Minor docs/spec/system-contracts/high-precision-timestamp.md missing Security Considerations.
R-011 Minor docs/spec/system-contracts/mega-access-control.md and mega-limit-control.md missing Security Considerations.
R-012 Minor docs/spec/evm/dual-gas-model.md:16,18 multi-sentence lines. Fix: one sentence per line.
R-013 Minor docs/spec/hardfork-spec.md:15-16,122 multi-sentence lines. Fix: one sentence per line.
R-014 Minor docs/spec/overview.md:65 multi-sentence line. Fix: break or consolidate.