Conversation
There was a problem hiding this comment.
Pull request overview
Adds a provider-agnostic .agent/ knowledge base and a new run-jovian-upgrade AI skill to guide engineers through the full Jovian local-fork upgrade pipeline, plus a few small op-tooling improvements (RPC/port configurability and post-upgrade-aware version verification).
Changes:
- Introduce
.agent/AGENT.mdand consolidate skills under.agent/skills/, including a newrun-jovian-upgradeorchestrator skill. - Make fork/mock/exec scripts respect externally provided
RPC_URLand allowfork_l1.shto run on a configurablePORT. - Update
verify-versions.shto dynamically discover post-upgrade topology (new CSC / ASR) and fix exec docs to referencesecrets/.env.signers.succinct200.
Reviewed changes
Copilot reviewed 12 out of 15 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/op-tooling/verify/verify-versions.sh | Adds live (post-upgrade) discovery of CSC/ASR to improve correctness on forks. |
| packages/op-tooling/fork/mock-sepolia.sh | Allows overriding RPC endpoint via RPC_URL. |
| packages/op-tooling/fork/mock-mainnet.sh | Allows overriding RPC endpoint via RPC_URL. |
| packages/op-tooling/fork/fork_l1.sh | Adds configurable PORT and improves quoting/error messaging. |
| packages/op-tooling/fork/README.md | Documents archive-RPC requirement and new PORT option. |
| packages/op-tooling/exec/exec-mocked.sh | Allows overriding RPC endpoint via RPC_URL. |
| packages/op-tooling/exec/exec-jovian-sepolia.sh | Adds NETWORK selection and a new chaos execution path. |
| packages/op-tooling/exec/README.md | Updates signer file reference to secrets/.env.signers.succinct200. |
| CLAUDE.md | Replaced with pointer to .agent/AGENT.md for provider-agnostic instructions. |
| .agent/AGENT.md | New unified project knowledge base (replaces prior CLAUDE.md content + Jovian ecosystem reference). |
| .agent/skills/run-jovian-upgrade/SKILL.md | New comprehensive skill for running the Jovian upgrade pipeline on a local Anvil fork. |
| .agent/skills/node-cache-update/SKILL.md | Migrated skill content into .agent/skills/. |
| .agent/skills/celo-release/SKILL.md | Migrated skill content into .agent/skills/. |
| .agent/skills/celo-release/examples.md | Adds example workflows for releases. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | OLD ASR (pre-v4) | `0xD73BA8168A61F3E917F0930D5C0401aA47e269D6` | | ||
| | OLD CSC (pre-v4) | **capture dynamically at T11** from `SystemConfig.superchainConfig()` and store as `OLD_CSC` in CONTEXT_BLOCK. Not hardcoded. | | ||
| | SuperchainConfig | `0x31bEef32135c90AE8E56Fb071B3587de289Aaf77` | | ||
| | Succinct impl target | **capture at T01** via `grep -m1 'SUCCINCT_IMPL=' $CELO_ROOT/packages/op-tooling/exec/exec-jovian-sepolia.sh` (or the `SUCCINCT_IMPL_ADDR` variable). Store as `SUCCINCT_IMPL_ADDR`. | | ||
| | EXPECTED_NEW_ASR | empty on sepolia (discover dynamically at T20) | |
There was a problem hiding this comment.
For sepolia, this doc says to capture the Succinct impl target by grepping for SUCCINCT_IMPL= in exec-jovian-sepolia.sh, but that string doesn't exist in the script (the impl address is encoded directly in the succinct-v2 CALLDATA). For chaos, the exec script requires the impl address via SUCCINCT_IMPL env, so there is nothing static to grep either. This section should specify the actual sepolia target address (or a deterministic extraction method) and define how chaos chooses/records the target address so T10 can plant code correctly.
| - `NETWORK=sepolia|chaos`, both modes: `./exec-jovian-sepolia.sh v4` (uses | ||
| hardcoded sigs; mock-sepolia.sh pre-setup is compatible) | ||
|
|
||
| **Task (Mode A mainnet)**: | ||
| ``` | ||
| cd $CELO_ROOT/packages/op-tooling/exec | ||
| RPC_URL=$RPC_URL VERSION=v4 PK=<real DEPLOYER_PK> SENDER=$SENDER \ | ||
| SIGNER_1_PK=0x57e639820c9154e011f46153bda6d502e1f8ebd376f87fadc1e317d3beeb10d8 \ | ||
| SIGNER_2_PK=0x5fb4edc777e9ad5889935f6cc0368a275be7f467b4b7eadf94cab92d667de592 \ | ||
| SIGNER_3_PK=0x82b0a6c773da129fc3604c6b85e68fa2c9cce0b21c3b63dd70b691e538269996 \ | ||
| SIGNER_4_PK=0x04cdae0aa51355d0bad6ec4e200138c71ca6686de3924382a048c9cbf38ddef9 \ | ||
| ./exec-mocked.sh | ||
| ``` | ||
|
|
||
| **Task (Mode B mainnet)**: | ||
| ``` | ||
| cd $CELO_ROOT/packages/op-tooling/exec | ||
| RPC_URL=$RPC_URL PK=<real DEPLOYER_PK> ./exec-jovian.sh v4 | ||
| ``` | ||
|
|
||
| **Task (sepolia/chaos)**: | ||
| ``` | ||
| cd $CELO_ROOT/packages/op-tooling/exec | ||
| RPC_URL=$RPC_URL NETWORK=$NETWORK PK=<real DEPLOYER_PK> ./exec-jovian-sepolia.sh v4 | ||
| ``` |
There was a problem hiding this comment.
The sepolia/chaos execution command omits required env vars for the chaos path. exec-jovian-sepolia.sh requires OPCM_ADDRESS for v4/v5 when NETWORK=chaos, so the skill needs to pass OPCM_ADDRESS=$OPCM_V4 (or $OPCM_V5) in addition to RPC_URL/NETWORK/PK. Also, the note that this path "uses hardcoded sigs" is not true for chaos (it signs with the deployer PK as the flat Safe owner).
| Same exec-script shape as T19 with the correct version string. Tier: `sonnet`. | ||
|
|
There was a problem hiding this comment.
For NETWORK=chaos, exec-jovian-sepolia.sh succinct-v2 requires SUCCINCT_IMPL (and optionally SC_OWNER_TARGET) to build the multicall calldata. The skill’s T30 card doesn’t mention passing these, so the chaos succ-v2 execution will exit early. Add chaos-specific instructions to pass SUCCINCT_IMPL=$SUCCINCT_IMPL_ADDR (or whatever address T10 planted) and clarify ownership target behavior.
| Same exec-script shape as T19 with the correct version string. Tier: `sonnet`. | |
| Same exec-script shape as T19, but with the correct version string and these | |
| network-specific requirements: | |
| - `NETWORK=sepolia`: run `./exec-jovian-sepolia.sh succinct-v2` with the usual env from T19. | |
| - `NETWORK=chaos`: `exec-jovian-sepolia.sh succinct-v2` must be given | |
| `SUCCINCT_IMPL=$SUCCINCT_IMPL_ADDR` (or whatever implementation address T10 planted) | |
| so the multicall calldata can be built. | |
| - `NETWORK=chaos`: `SC_OWNER_TARGET` is optional; pass it only if the ownership target | |
| for `SystemConfig` should be explicitly overridden during calldata construction. | |
| If omitted, the script's default/current ownership target behavior applies. | |
| Tier: `sonnet`. |
| LIVE_CSC=$(cast call "$SYSTEM_CONFIG_PROXY" "superchainConfig()(address)" -r "$RPC_URL" 2>/dev/null || echo "") | ||
| if [ -n "$LIVE_CSC" ] && [ "$LIVE_CSC" != "$ZERO_ADDR" ]; then | ||
| CELO_SUPERCHAIN_CONFIG_PROXY="$LIVE_CSC" | ||
| fi | ||
|
|
||
| LIVE_PG_IMPL=$(cast call "$DISPUTE_GAME_FACTORY_PROXY" "gameImpls(uint32)(address)" 1 -r "$RPC_URL" 2>/dev/null || echo "") | ||
| if [ -n "$LIVE_PG_IMPL" ] && [ "$LIVE_PG_IMPL" != "$ZERO_ADDR" ]; then | ||
| LIVE_ASR=$(cast call "$LIVE_PG_IMPL" "anchorStateRegistry()(address)" -r "$RPC_URL" 2>/dev/null || echo "") | ||
| if [ -n "$LIVE_ASR" ] && [ "$LIVE_ASR" != "$ZERO_ADDR" ]; then | ||
| ANCHOR_STATE_REGISTRY_PROXY="$LIVE_ASR" | ||
| fi |
There was a problem hiding this comment.
The new live-discovery calls rely on $SYSTEM_CONFIG_PROXY and $DISPUTE_GAME_FACTORY_PROXY being correct for the selected NETWORK. In this script, the Chaos addresses currently disagree with the rest of op-tooling (e.g., fork/mock-sepolia.sh and op-deployer bootstrap scripts use SystemConfig=0x6baf... and DGF=0x338a...). As a result, verify-versions will query the wrong contracts on NETWORK=chaos and may overwrite CELO_SUPERCHAIN_CONFIG_PROXY / ANCHOR_STATE_REGISTRY_PROXY with unrelated values. Align the Chaos address constants here with the ones used by the fork/mock + exec tooling (or source them from a single shared config).
| | `NEW_CSC` | T20 | `cast call $SYSTEM_CONFIG "superchainConfig()(address)"` | | ||
| | `NEW_ASR` | T20 | `cast call <PERM_GAME_V4> "anchorStateRegistry()(address)"` | | ||
| | `OLD_CSC` | **Mode A mainnet**: §B.4 literal at T01. **Other networks**: T11 dynamic capture from `SystemConfig.superchainConfig()` on the pre-v4 fork state | see §B.4b sepolia note | | ||
| | `SUCCINCT_IMPL_ADDR` | **Mainnet**: §B.4 literal at T01. **Sepolia**: T01 grep from `exec-jovian-sepolia.sh SUCCINCT_IMPL=` line. **Chaos**: T01 grep from same script's chaos branch. | §B.4 / §B.4b | |
There was a problem hiding this comment.
The instructions for populating SUCCINCT_IMPL_ADDR via grep ... 'SUCCINCT_IMPL=' exec-jovian-sepolia.sh don't match the actual exec script: for sepolia the succinct impl address is embedded in hardcoded CALLDATA (no SUCCINCT_IMPL= assignment), and for chaos it is provided via env at runtime. This will cause T01/T10 to fail to identify the address to anvil_setCode and later upgrades to revert. Update the source-of-truth for SUCCINCT_IMPL_ADDR (e.g., hardcode the sepolia address from the exec script, and require an explicit value for chaos / derive it from T10 outputs).
| | `SUCCINCT_IMPL_ADDR` | **Mainnet**: §B.4 literal at T01. **Sepolia**: T01 grep from `exec-jovian-sepolia.sh SUCCINCT_IMPL=` line. **Chaos**: T01 grep from same script's chaos branch. | §B.4 / §B.4b | | |
| | `SUCCINCT_IMPL_ADDR` | **Mainnet**: §B.4 literal at T01. **Sepolia**: T01 static literal from the hardcoded Succinct implementation address embedded in `exec-jovian-sepolia.sh` calldata (do **not** grep for `SUCCINCT_IMPL=`). **Chaos**: T01/T10 must obtain this from an explicit runtime value or derive it from T10 outputs; do **not** infer it by grepping the exec script. | §B.4 / §B.4b / T10 evidence | |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e39980f997
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5387e70827
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| - `NETWORK=sepolia|chaos`: `./exec-jovian-sepolia.sh succinct-v2` (the `-v2` spelling | ||
| differs — `succinct-v2` NOT `succ-v2`) |
There was a problem hiding this comment.
This step instructs the runner to execute ./exec-jovian-sepolia.sh succinct-v2, but the updated script in this same commit only accepts v4|v5|succ-v2 and exits on any other value (packages/op-tooling/exec/exec-jovian-sepolia.sh lines 5-8). In sepolia/chaos flows, T30 will therefore fail deterministically at the final upgrade phase, preventing CP3/CP4 completion.
Useful? React with 👍 / 👎.
| `SystemConfig.superchainConfig()` on the pre-v4 fork and copied into | ||
| CONTEXT_BLOCK before T12 dispatches), and `SUCCINCT_IMPL_ADDR` is captured | ||
| at T01 with | ||
| `grep -m1 'SUCCINCT_IMPL[_ADDR]*=' $CELO_ROOT/packages/op-tooling/exec/exec-jovian-sepolia.sh | sed 's/.*=//'`. |
There was a problem hiding this comment.
The T01 command extracts SUCCINCT_IMPL_ADDR by grepping SUCCINCT_IMPL[_ADDR]*= from exec-jovian-sepolia.sh, but that script has no matching assignment, so this capture returns empty (or errors) instead of an address. Downstream tasks in this skill later call cast against $SUCCINCT_IMPL_ADDR, so sepolia/chaos runs can fail or validate the wrong target because the context variable was never populated correctly.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 880e014755
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| **Task (sepolia/chaos)**: | ||
| ``` | ||
| cd $CELO_ROOT/packages/op-tooling/exec | ||
| RPC_URL=$RPC_URL NETWORK=$NETWORK PK=<real DEPLOYER_PK> ./exec-jovian-sepolia.sh v4 |
There was a problem hiding this comment.
For NETWORK=chaos, exec-jovian-sepolia.sh now hard-requires OPCM_ADDRESS (v4/v5) and SUCCINCT_IMPL (succ-v2) before it can execute (packages/op-tooling/exec/exec-jovian-sepolia.sh checks these at startup). This task template only exports RPC_URL, NETWORK, and PK, so chaos executions fail immediately with missing-env errors instead of reaching CP1/CP2/CP3; T25 and T30 inherit the same broken command shape.
Useful? React with 👍 / 👎.
|
|
||
| **Task (Mode B)**: only check `$CELO_ROOT/packages/op-tooling/exec/exec-jovian.sh` | ||
| (mainnet) or `exec-jovian-sepolia.sh` (sepolia/chaos) exists AND | ||
| `$CELO_ROOT/secrets/.env.signers.{v4,v5,succinct200}` are decrypted. If |
There was a problem hiding this comment.
The Mode B prerequisite currently requires secrets/.env.signers.{v4,v5,succinct200} for every network, but sepolia/chaos execution paths use exec-jovian-sepolia.sh and do not consume those decrypted signer files. On sepolia/chaos this creates a false preflight failure that blocks otherwise valid Mode B runs even though downstream commands never read those files.
Useful? React with 👍 / 👎.
Description
Introduces a comprehensive AI skill (
run-jovian-upgrade) that interactively guides engineers through the complete Jovian upgrade pipeline (v4.1.0 → v5.0.0 → Succinct v2) on a local Anvil fork. The skill orchestrates work across 6 repositories (Celo, Optimism, Optimism2, SuperchainOps, CeloSuperchainOps, Succinct) with checkpoint-based state verification between each upgrade phase.Previously, running the Jovian upgrade locally required deep tribal knowledge of the correct script order, env vars, Safe nonce expectations, branch requirements, and cross-repo dependencies. This skill captures that knowledge in a structured, repeatable workflow that any engineer can follow — even without prior upgrade experience.
The skill covers: fork setup with port conflict handling, Safe multisig mocking, op-deployer bootstrap (v4/v5), Succinct FDG deployment with config-driven vkey population, SuperchainOps simulation, CeloSuperchainOps EIP-712 signing, sequential upgrade execution with 4 on-chain checkpoints, and domain-specific validations (new CeloSuperchainConfig, new ASR, game→ASR pointers, SystemConfig ownership transfer).
Additionally migrates the project knowledge base from the Claude Code-specific
CLAUDE.mdto a provider-agnostic.agent/AGENT.mdstructure, and consolidates all skills under.agent/skills/.Other changes
celo-release,node-cache-update) from.cursor/skills/to.agent/skills/(content unchanged).agent/skillssymlink, replaced with real directory.cursor/skills/directory (content migrated)CLAUDE.mdreplaced with a thin pointer to.agent/AGENT.md— keeps Claude Code compatibility while being LLM-agnostic.agent/AGENT.mdincludes new sections: Repository Dependency Map, Network Configuration Reference (Safe addresses, proxy addresses, fork block numbers), Default Mocked Accounts, X-Ray Health Rules reference, and Upgrade Pipeline TimelineTested
Manually tested the full skill flow end-to-end on a local Anvil fork:
Related issues
Backwards compatibility
No backwards compatibility concerns. This PR only adds new files under
.agent/and modifiesCLAUDE.mdto point to the new location. No existing scripts, contracts, or CI workflows are affected. The migrated skills retain identical content.Documentation
.agent/AGENT.md— Unified project knowledge base (replacesCLAUDE.mdcontent + Jovian ecosystem documentation).agent/skills/run-jovian-upgrade/SKILL.md— Interactive upgrade skill (1045 lines, 6 phases, 4 checkpoints)