docs, .claude: add hardfork rollout review guidance#2229
Conversation
- add hardfork rollout rule for fork config, genesis, fork ID, VM, consensus, and miner paths - document runtime config vs packaged genesis parity checks - call out the packaged-genesis-only activation failure class - add standalone AGENTS guidance for direct repo sessions
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.
Tip: disable this comment in your organization's Code Review settings.
There was a problem hiding this comment.
Pull request overview
Adds repo-local AI review guidance for Bor hardfork rollout checks, focusing on runtime/genesis parity, fork activation wiring, fork ID behavior, and boundary test expectations.
Changes:
- Adds
.claude/rules/hardfork-rollout.mdwith path-scoped hardfork review guidance. - Updates
AGENTS.mdto list the new rule and add standalone hardfork rollout review instructions.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
AGENTS.md |
Adds the hardfork rollout rule to the security rules table and documents standalone review checks. |
.claude/rules/hardfork-rollout.md |
Introduces the hardfork rollout review checklist and path-scoped trigger configuration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #2229 +/- ##
===========================================
- Coverage 52.38% 52.36% -0.03%
===========================================
Files 885 885
Lines 155855 155904 +49
===========================================
- Hits 81644 81638 -6
- Misses 68979 69025 +46
- Partials 5232 5241 +9 see 20 files with indirect coverage changes 🚀 New features to boost your workflow:
|
The previous frontmatter listed 5 specific files (contracts, eips, gas_table, jump_table, operations_acl) which was tighter than the consensus-critical EVM surface warrants. Hardfork-gated behavior can also land in evm.go, instructions.go, interpreter.go, gas.go, opcodes.go, etc. — those changes would not have triggered the rule. Broadens to core/vm/*.go so the rule auto-loads on any top-level VM file. The rule's Trigger Conditions let the agent quickly conclude "not hardfork-shaped" when the diff doesn't touch fork-relevant code, so the extra noise on unrelated VM edits is acceptable for the coverage win. Addresses Copilot inline review comment on PR #2229.
|
@claude review once |
|
Claude finished @pratikspatil024's task in 1m 54s —— View job Code Review
SummaryThis is a well-structured docs/rules-only PR that adds hardfork rollout review guidance. The content addresses a real and dangerous failure class — fork blocks present in genesis JSON but missing from Go runtime presets — and the guidance is actionable. No issues found that would block merge. FindingsNo bugs or security issues — this is purely documentation. Two minor observations below. 1. Scope column in AGENTS.md table omits
|
- include params/protocol_params.go in the AGENTS rule scope - note that AGENTS hardfork guidance mirrors the path-scoped rule
|
@claude addressed both nits in the follow-up commit:
Thanks for the review. |
|
Claude finished @pratikspatil024's task in 29s —— View job Verifying follow-up commit
Confirmed both nits addressed in
LGTM — nothing else from my side. Thanks for the quick follow-up. |
- include recursive core/vm paths in the hardfork rollout rule - make the AGENTS rule scope explicit and consistent
|
Summary
Adds standalone hardfork rollout review guidance for Bor.
Hardforks in Bor require coordinated wiring across runtime chain presets, packaged genesis files, fork ID calculation, config compatibility, startup visibility, EVM/precompile behavior, consensus logic, and miner behavior. This PR adds a
path-scoped Claude rule plus repo-level AGENTS guidance so AI-assisted reviews can catch incomplete hardfork rollouts even when run directly inside this repository.
The new guidance specifically calls out the drift class where a fork block is present in packaged genesis JSON but missing from the normal runtime Go chain presets. In that case a node started through the normal
bor server --config ...path can load
Bor.<Fork>Block == nil, so fork checks such asBor.Is<Fork>(num)never activate on the standard startup path.What changed
.claude/rules/hardfork-rollout.mdwith a path-scoped frontmatter that auto-loads on edits toparams/,internal/cli/server/chains/,builder/files/genesis-*.json,core/forkid/forkid.go, fork-gated files undercore/vm/,consensus/bor/bor.go, andminer/worker.go.AGENTS.mdsecurity rules table.AGENTS.mdso the guidance applies even when an AI agent is launched directly inside this repository, outside the PoS team workspace.params.BorMainnetChainConfigparams.AmoyChainConfiginternal/cli/server/chains/mainnet.gointernal/cli/server/chains/amoy.goN-1/N/N+1activation-boundary test coverageExecuted tests
Docs / rules-only change; no runtime code touched.
Also checked the updated markdown files for trailing whitespace.
The rule body was empirically validated by running fresh-context AI reviews against three historical hardfork-shaped PRs across bor and heimdall-v2. Each case was flagged at CRITICAL severity with concrete file:line evidence; per-case
verdicts and full findings live in the corresponding workspace PR.
Rollout notes
No runtime behavior changes. This only affects repo-local AI guidance and review checklists.
Future hardfork PRs should use this rule to verify activation blocks, runtime config parity, packaged genesis parity, fork ID behavior, startup visibility, N-1/N/N+1 boundary tests, and cross-client parity where consensus output changes.
Related PRs