fix(misc): docs weekly audit 2026-08-03

[cursor]

Weekly Docs Audit - 2026-08-03

Automated audit of all Markdown files. Issues requiring human review are listed below.

---

Fixed Issues

Stale Version Claims Auto-Fixed (1)

File	Line	Old Version	New Version	Canonical Source
CONTRIBUTING.md	9	JDK 21	JDK 25	buildSrc/src/main/groovy/net.consensys.zkevm.kotlin-common-minimal-conventions.gradle (JavaLanguageVersion.of(25))

Stale Terminology Auto-Fixed (3)

File	Line	Old Reference	New Reference	Canonical Source
docs/architecture-description.md	253	L1 LineaService	L1 LineaRollup	contracts/src/rollup/LineaRollup.sol (contract name)
docs/architecture-description.md	274	L1 LineaService smart contract	L1 LineaRollup smart contract	contracts/src/rollup/LineaRollup.sol
docs/architecture-description.md	799	`LineaService.finalizeBlocks`	`LineaRollup.finalizeBlocks`	contracts/src/rollup/LineaRollupBase.sol:359 (function finalizeBlocks)

Stale Command Names Auto-Fixed (7)

Renamed script names (test:e2e:local, test:e2e:fleet:local, test:e2e:liveness:local) to match the canonical scripts defined in e2e/package.json (test:local, test:fleet:local, test:liveness:local).

File	Line	Old Command	New Command
docs/tech/development/README.md	38	pnpm run test:e2e:local	pnpm run test:local
docs/tech/development/README.md	420	pnpm run test:e2e:local	pnpm run test:local
docs/tech/development/README.md	423	pnpm run test:e2e:local -- messaging.spec.ts	pnpm run test:local -- messaging.spec.ts
docs/tech/development/README.md	426	pnpm run test:e2e:fleet:local	pnpm run test:fleet:local
docs/tech/development/README.md	429	pnpm run test:e2e:liveness:local	pnpm run test:liveness:local
docs/tech/components/e2e.md	596-599	pnpm run test:e2e:local (2x)	pnpm run test:local
docs/tech/components/e2e.md	602-605	pnpm run test:e2e:{fleet,liveness}:local	pnpm run test:{fleet,liveness}:local

Canonical source for all command renames: e2e/package.json scripts block.

Stale Cross-References Auto-Fixed (0)

None.

---

Remaining Issues (Requires Human Review)

[HIGH] Terminology conflict: shnarf defined with incompatible formulas

• Location A: contracts/docs/workflows/operations/blobSubmissionAndFinalization.md:21 - describes newShnarf = H(oldShnarf || appendedValue) as a stack/append model.
• Location B: docs/features/rollup.md:117 - defines shnarf = keccak256(parentShnarf, snarkHash, finalStateRootHash, dataEvaluationPoint, dataEvaluationClaim) as a fixed 5-field tuple.
• Why ambiguous: Both purport to describe the current shnarf construction but use fundamentally different formulas. Requires a subject-matter expert to reconcile against the actual _computeShnarf implementation.

[HIGH] Permission inconsistency: OPERATOR_ROLE absent from LineaRollup role catalog

• Location A: docs/features/rollup.md:64 - lists OPERATOR_ROLE with capabilities "Submit blobs, finalize blocks".
• Location B: docs/tech/components/contracts.md:180 - shows submitBlobs(...) ... onlyRole(OPERATOR_ROLE).
• Location C: contracts/docs/workflows/administration/roleManagement.md:64-81 - LineaRollup role list omits OPERATOR_ROLE entirely.
• Why ambiguous: Correct action depends on whether the operational runbook role list is deliberately curated or is missing an entry. Not a straightforward text swap.

[HIGH] Permission inconsistency: SECURITY_COUNCIL_ROLE on-chain vs multisig charter

• Location A: docs/features/pause-and-security.md:40,127-130 - attributes indefinite pausing, unpausing, and cooldown reset to on-chain SECURITY_COUNCIL_ROLE.
• Location B: contracts/docs/workflows/administration/roleManagement.md:64-107 - exhaustive role lists for LineaRollup, L2MessageService, TokenBridge; SECURITY_COUNCIL_ROLE not listed.
• Location C: contracts/docs/security-council-charter.md:11-17 - describes Security Council as Gnosis Safe multisigs.
• Why ambiguous: Unclear whether SECURITY_COUNCIL_ROLE is a real on-chain role or shorthand for multisig-held admin roles. Requires SME review.

[HIGH] Enumerated value mismatch: pause role name vs pause-type enum for blob submission

• Location A: contracts/docs/workflows/administration/roleManagement.md:79-80 - uses PAUSE_L2_BLOB_SUBMISSION_ROLE / UNPAUSE_L2_BLOB_SUBMISSION_ROLE.
• Location B: contracts/docs/workflows/administration/pausing.md:61 - uses STATE_DATA_SUBMISSION_PAUSE_TYPE.
• Location C: docs/features/pause-and-security.md:34 - uses STATE_DATA_SUBMISSION for the same operation class.
• Why ambiguous: Different naming conventions for the same functional area; would need to verify contract source before renaming any doc.

[MEDIUM] Lifecycle mismatch: E2E local-stack prerequisite differs across docs

• Location A: AGENTS.md:233 - "Protocol E2E tests require a running local stack (make start-env)".
• Location B: docs/get-started.md:23 - documents make start-env-with-tracing-v2.
• Location C: e2e/README.md:20 - documents make start-env-with-tracing-v2-ci.
• Why ambiguous: Three make targets have different deployment scopes; the correct prerequisite depends on which tests are being run (baseline vs tracing vs CI parity).

[MEDIUM] Lifecycle mismatch: who anchors L2->L1 Merkle roots on L1

• Location A: docs/features/messaging.md:59-60 - shows Prover -> L1 anchoring in the sequence diagram.
• Location B: contracts/docs/workflows/messaging/canonicalL2ToL1Messaging.md:17-18 - Coordinator anchors messaging Merkle root(s) on L1 during finalization.
• Location C: docs/architecture-description.md:941-949 - Prover computes; anchoring happens during finalization without naming the submitter.
• Why ambiguous: Prover cannot send L1 transactions in practice, so the messaging.md sequence diagram is likely simplified; needs an author with knowledge of the real anchoring flow to fix without breaking the diagram.

[MEDIUM] Terminology drift: ADMIN_ROLE vs DEFAULT_ADMIN_ROLE

• Location A: contracts/integrity-verifier/README.md:360 - example: hasRole(ADMIN_ROLE, addr).
• Location B: docs/features/integrity-verifier.md:53 - example: hasRole(ADMIN_ROLE, addr).
• Location C: contracts/integrity-verifier/verifier-core/src/constants.ts:133 - canonical role hash keccak256("DEFAULT_ADMIN_ROLE").
• Why ambiguous: ADMIN_ROLE appears as an illustrative role name in examples; different verified contracts may legitimately expose different role names. Choosing between ADMIN_ROLE (illustrative) and DEFAULT_ADMIN_ROLE (OpenZeppelin canonical) requires editorial judgement.

[MEDIUM] Completion criteria drift: E2E success vs stack boot

• Location A: docs/getting-started/lineth-stack/AGENTS.md:92-93 - success requires observed finalizeBlocks and advancing currentL2BlockNumber; explicitly notes Submit Blobs is not finalization.
• Location B: docs/get-started.md:20-24 - implies success from make start-env-with-tracing-v2 + pnpm -F e2e run test:local without a finalization criterion.
• Why ambiguous: The two audiences (contributors vs external users) may reasonably need different "done" thresholds; requires editorial decision.

[LOW] Stale cross-reference: broken anchor in contracts/README.md

• Location: contracts/README.md:45 - links to ../docs/audits.md#linea-rollup-l2messageservice-and-tokenbridge-smart-contract-audits.
• Problem: Target file exists but the anchor does not. Closest current heading is ## Rollup, message service, and token bridge (slug: rollup-message-service-and-token-bridge). Per audit rules, broken anchors are always AMBIGUOUS (not auto-fixed).

---

Audit Coverage

Checked 246 files (259 total, minus 12 CHANGELOG.md files and 1 generated artifact) across all 7 categories:

• Terminology conflicts
• Protocol contradictions
• Lifecycle mismatches
• Permission inconsistencies
• Completion criteria inconsistencies
• Enumerated value mismatches
• Stale cross-references

Canonical version sources cross-referenced: .nvmrc (Node 24.18.0), package.json (pnpm 11.9.0), buildSrc/.../kotlin-common-minimal-conventions.gradle (JDK 25), prover/go.mod (Go 1.25.7), contracts/hardhat.config.ts (Solidity 0.8.33), contracts/package.json (OpenZeppelin 4.9.6), gradle/wrapper/gradle-wrapper.properties (Gradle 9.6.1).