Conversation
Add foundational AI agent context files so that any AI coding agent or new engineer can produce correct, safe PRs without guessing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
There was a problem hiding this comment.
Pull request overview
Adds an “AI-first” documentation layer that centralizes project context, operational/security invariants, and agent/testing policies to guide contributors and AI agents working in this repo.
Changes:
- Introduces
AGENTS.mdas the primary agent entry point (overview, commands, structure, conventions, PR requirements, gotchas). - Adds repo-specific agent policies under
.ai/rules/(security, agent-safety, testing). - Adds
.ai/context/glossary.mdas lightweight domain vocabulary/context.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
CLAUDE.md |
Provides a short “required reading” entrypoint pointing to AGENTS.md and .ai/ rules. |
AGENTS.md |
Defines project overview, commands, directory structure, conventions, security invariants, operating mode, and PR requirements. |
.ai/rules/testing.md |
Documents required CI checks and local testing conventions (including fork testing guidance). |
.ai/rules/security.md |
Captures non-negotiable security invariants around access control, minting, upgrades, migration, crypto, deployment, and math. |
.ai/rules/agent-safety.md |
Defines trusted instruction precedence, untrusted input policy, never-do list, and escalation triggers. |
.ai/context/glossary.md |
Adds POL-domain glossary intended for quick reference by humans/agents. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Term | Definition | | ||
| |------|-----------| | ||
| | **POL** | Polygon Ecosystem Token — the ERC-20 token on Ethereum L1 that upgrades MATIC. Contract: `PolygonEcosystemToken.sol`. | | ||
| | **MATIC** | The legacy Polygon token on Ethereum. POL replaces it at a 1:1 ratio via the migration contract. | |
There was a problem hiding this comment.
The glossary table is written with a double leading pipe (|| Term | Definition |, ||------|...) which GitHub renders as an extra empty first column / malformed table. Use standard table row syntax with a single leading pipe (| Term | Definition |) throughout this file so it renders correctly.
| - **Function/variable names:** camelCase (`mintPerSecondCap`, `inflatedSupplyAfter`) | ||
| - **Constants:** UPPER_SNAKE_CASE (`EMISSION_ROLE`, `START_SUPPLY`) | ||
| - **Interfaces:** Prefixed with `I` (`IPolygonEcosystemToken`) | ||
| - **NatSpec:** All public/external functions must have NatSpec documentation. Include `@custom:security-contact security@polygon.technology` on contracts. |
There was a problem hiding this comment.
This claims all public/external functions must have NatSpec, but the current codebase has public/external functions without NatSpec blocks (e.g., DefaultEmissionManager.initialize() / reinitialize() in src/DefaultEmissionManager.sol). To avoid creating a rule the repo doesn’t currently follow, consider scoping this to “new/modified public/external functions” or noting that @inheritdoc is acceptable where interfaces exist.
| - **NatSpec:** All public/external functions must have NatSpec documentation. Include `@custom:security-contact security@polygon.technology` on contracts. | |
| - **NatSpec:** All new or modified public/external functions must have NatSpec documentation. Using `@inheritdoc` is acceptable where an interface or base contract already documents the function. Include `@custom:security-contact security@polygon.technology` on contracts. |
| - Fork tests use `vm.createSelectFork()` with the `RPC_MAINNET` environment variable. | ||
| - ALWAYS pin fork tests to a specific block number for reproducibility. | ||
| - Fork tests are in `test/upgrade/` for upgrade validation. |
There was a problem hiding this comment.
The “Fork Tests” section implies fork tests live in test/upgrade/, but there are fork-dependent tests outside that folder (e.g., test/PolygonMigration.t.sol calls vm.createFork(vm.rpcUrl("mainnet"), ...) in setUp()). Consider rewording this to distinguish “upgrade validation fork tests” vs other fork-using tests, or document that some core tests also require RPC_MAINNET.
| - Fork tests use `vm.createSelectFork()` with the `RPC_MAINNET` environment variable. | |
| - ALWAYS pin fork tests to a specific block number for reproducibility. | |
| - Fork tests are in `test/upgrade/` for upgrade validation. | |
| - Fork-based tests use `vm.createSelectFork()` or `vm.createFork()` with the `RPC_MAINNET` environment variable. | |
| - ALWAYS pin fork tests to a specific block number for reproducibility. | |
| - Upgrade validation fork tests live in `test/upgrade/`. | |
| - Some core tests outside `test/upgrade/` also use mainnet forks and therefore require `RPC_MAINNET` to be set. |
Summary
AGENTS.mdas the universal AI agent entry point with all required sections (project overview, tech stack, runnable commands, directory structure, coding conventions, security invariants, trust model, agent operating mode, PR requirements, known gotchas, doc pointers).ai/rules/security.mdwith 25+ repo-specific non-negotiable security rules covering access control, minting, upgrade safety, migration, cryptography, deployment, and math safety.ai/rules/agent-safety.mddefining untrusted input policy, never-do list, and POL-specific escalation triggersTest plan
forge buildcompiles successfullyforge test -vvv— 17/17 non-fork tests pass (2 fork tests skip withoutRPC_MAINNET, as documented in Known Gotchas)🤖 Generated with Claude Code