docs: governance timelock runbook

[hardyjosh]

docs/TIMELOCK.md: role model (Safe = proposer/canceller/executor, 48h min
delay, timelock self-administered, deploy key never holds anything),
deterministic per-chain addresses + pin constants, the four-step per-chain
rollout (deploy broadcast -> pin PR -> CI-authored Safe bundle -> execute
-> post-execution flip PR), how future governance actions work
(schedule -> 48h -> execute, batching, cancellation), the invariant
surface, the dedicated-canceller placeholder, and explicit out-of-scope
follow-ups (beacon ownership, HyperEVM).

CLAUDE.md: Governance section pointing script authors at
LibTimelockInvariants.timelockForChainId and the schedule/execute pattern
for any bundle touching onlyOwner/_ADMIN surfaces.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01RquYKmoEVSfuVHy8kwn1yT

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8cd02ed8-14ed-4425-bd19-117c68891f83

📥 Commits

Reviewing files that changed from the base of the PR and between 1065fc9 and 229c61c.

📒 Files selected for processing (2)

• CLAUDE.md
• docs/TIMELOCK.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[hardyjosh]

• pin(timelock): hydrate the permissionless governance timelocks #303
• feat(timelock): permissionless execution #302
• feat(timelock): migrate the upgrade beacons under the timelock too #290
• docs: governance timelock runbook #288 👈 (View in Graphite)
• feat(invariants): governance-timelock migration-window forcing functions #287
• feat(script): 20260729-migrate-governance-to-timelock Safe bundle #286
• feat(script): 20260729-deploy-governance-timelock broadcast #285
• feat(lib): LibTimelockInvariants + authoriser grant-map admin-holder parameterisation #284
• ops(script): HyperEVM token deploy (RAI-1511) #278 : 1 other dependent PR (#291 )
• pin(invariants): HyperEVM invariant surface (RAI-1511) #277
• ops(script): HyperEVM beacon-owner migration + 0.1.1 beacon lib generalisation (RAI-1511) #276
• feat(multichain): HyperEVM token-owner Safe pin plumbing (RAI-1511) #275
• feat(multichain): HyperEVM V4 authoriser clone pin plumbing (RAI-1511) #274
• feat(authoriser): additional service signer — canonical pin + provisioning #280
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[thedavidmeister]

Reviewed 229c61c: ship — the governance timelock runbook and CLAUDE.md governance section, fact-checked claim by claim against code, tests, and live chain state: role model, deploy-key-holds-nothing, no-open-roles, canceller mechanics, owner-freeze surface (verified onlyOwner in OwnerFreezable), operating mechanics, deadline paragraph matching the merged forcing function, and the frozen-pin invariants section. Docs-only diff; all checks green; no unresolved review threads.
Rulings-conformance: checked against every ruling stated for this work and the repo CLAUDE.md. (1) "timelock code needs to be a constant" — obeyed: the invariants section documents the pinned TIMELOCK_RUNTIME_CODEHASH / frozen TIMELOCK_CREATION_CODE doctrine (d640d17). (2) "zero is a checked case" — obeyed: the Addresses section and rollout steps were corrected (229c61c) to the pin-with-arm doctrine — zero refused by every consumer, equality unconditional via testPinsMatchDerivedAddresses — replacing the retired address(0)-until-hydrated flow, and the deploy step now describes the real single multi-chain dispatch. (3) comments describe CURRENT behavior only — obeyed: rollout-progress framing removed where it had gone stale; the beacons-out-of-scope section is transiently accurate at this layer and is superseded by the next stack layer (#290) editing that exact section. (4) docs-only: no code, pointer, or CHANGELOG obligations.