A stale roles{} anchor now refuses instead of silently snapshotting the replaced contract, with REANCHOR=true as the explicit opt-in.

[aelmanaa]

This pull request introduces support for a new REANCHOR flag to the snapshot-chain process, clarifies its usage throughout the documentation, and improves the handling and testing of roles anchor drift scenarios. The main goal is to ensure that after a redeploy or repoint, explicit operator action is required to move the roles anchor, preventing accidental or silent changes to critical configuration. Several code and documentation updates reinforce this behavior, improve testability, and make the process more robust and transparent.

Enhancements to roles anchor handling and snapshot-chain behavior:

• The Makefile now supports a REANCHOR environment variable for snapshot-chain, allowing explicit re-anchoring of roles after a repoint. This is reflected in both the command and its help text. [1] [2] [3]
• The roles resolution logic in RolesSnapshot.sol is updated to enforce that a stale anchor refuses to resolve unless REANCHOR=true is set, preventing accidental overwrites and requiring explicit operator intent for anchor movement. The logic is also clarified and better documented. [1] [2]

Documentation updates for clarity and operator guidance:

• All relevant documentation (roles.md, config-schema.md, deployed-addresses.md) is updated to explain the refusal behavior of snapshot-chain in the presence of anchor drift, and to document the correct use of REANCHOR=true for deliberate re-anchoring. [1] [2] [3]
• Troubleshooting guides and runbooks are expanded to cover common failure cases and clarify the remedies, including explicit instructions for supplying keystore passwords and using REANCHOR=true.

Testing and warning improvements:

• The VerifyChain.s.sol script now tracks the last warning message in addition to counts, allowing unit tests to assert exactly which warning fired. It also resets warning/fail state between tests for isolation and clarity. [1] [2] [3]
• The anchor drift warning logic is refactored to distinguish between malformed, zero, and stale anchors, providing more precise and actionable warning messages. [1] [2] [3]

Minor codebase cleanups:

• Unused imports (e.g., RegistryWriter in RolesSnapshot.sol) are removed for clarity.

These changes collectively make the roles anchoring process more robust, explicit, and testable, and provide clearer guidance to operators and contributors.

[github-actions]

👋 aelmanaa, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!