diff --git a/AGENTS.md b/AGENTS.md index f42c2567..e21d1a53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,13 @@ -This is a repo of onchain operational tasks. Each network has its own directory with each individual task as a sub-directory. +This is a repo of onchain operational tasks. Active EVM tasks live under `active/evm/tasks/`; one task directory may contain configurations for multiple networks under `config//`. + +Active EVM task lifecycle: + +- A task directory represents one logical operation and carries its shared Makefile, scripts, and facilitator guide across network rollouts. Add another `config//` to the existing task instead of creating a duplicate task solely to change networks. +- A task with multiple network configurations must require `TASK_NETWORK` on each `make` command line. Do not set a mutable default or rely on an exported environment value; use `make TASK_NETWORK= ` so the selected network is visible at every invocation. +- Keep the task-root `FACILITATOR.md` authoritative and network-agnostic, using explicit placeholders such as `TASK_NETWORK=` and paths under `config//`. Per-network facilitator files are discouraged because they duplicate configuration and drift from the shared procedure. Only consider one as a last resort when a network has a materially different procedure that cannot be expressed in the root guide, `.env`, or signer README. If unavoidable, place only the procedural delta in `config//FACILITATOR.md` and link to it from the root guide. +- Keep a task under `active/evm/tasks/` while any currently intended network rollout remains pending. Do not run `make archive-task` between network rollouts; archive only after every intended network configuration is executed or canceled and its final artifacts are committed. +- Treat `archive/evm/` as historical. Do not edit or execute an archived task in place. If the same operation later needs another network rollout, restore the entire task directory to `active/evm/tasks/` before adding that network. +- Store network-specific deployment address artifacts such as `addresses.json` under `config//`. Keep Forge broadcast records at task scope under `records/`; Foundry separates them by script and chain ID. Task writing: diff --git a/README.md b/README.md index 75b9814b..7c146370 100644 --- a/README.md +++ b/README.md @@ -105,47 +105,36 @@ All address variables are prefixed with `export` so they are available to child ## Directory structure -Active EVM tasks live under `active/evm/`, which is a single shared Foundry -project rather than a standalone project per task. A single `active/evm/Makefile` -selects the active task via `TASK_ID` / `TASK_NETWORK`, reusable operation -scripts are shared across tasks under `script/common//`, and each task -directory holds only its own config, docs, and (per-network) validations and -signatures: +Active EVM tasks share the Foundry project under `active/evm/`, while each task owns its Makefile, facilitator guide, network configurations, signatures, and execution records. Reusable operation scripts live under `script/common//`; one-off scripts stay with their task. ```text active/evm/ -├── Makefile # shared; selects the task via TASK_ID / TASK_NETWORK -├── foundry.toml # shared Foundry config (base-contracts v8.2.1) +├── foundry.toml # shared Foundry configuration ├── script/ │ └── common/ # reusable scripts, shared across tasks │ └── / # bridge, funding, gas, ownership, safe, superchain, verifier-update └── tasks/ └── / - ├── FACILITATOR.md + ├── Makefile # task dependencies, validation, approvals, and execution + ├── FACILITATOR.md # network-agnostic facilitator procedure + ├── script/ # optional one-off task scripts ├── config/ │ └── / - │ ├── .env # task inputs + BASE_CONTRACTS_COMMIT + RECORD_STATE_DIFF - │ ├── network.env # RPC, chain ids, Safe/contract addresses - │ ├── README.md # status + description (parsed by the signer tool) + │ ├── .env # network-specific task inputs + BASE_CONTRACTS_COMMIT + │ ├── addresses.json # generated network-specific deployment addresses + │ ├── README.md # status + description parsed by the signer tool │ └── validations/ # generated per-signer validation JSON - └── signatures/ - └── / # task-origin signatures (when required) + ├── signatures/ + │ └── / # task-origin signatures when required + └── records/ + └──