CMTAT v3.3.0-rc3

.claude/tree/contracts_tree.txt

@@ -3,8 +3,8 @@ contracts
 │   ├── allowlist
 │   │   ├── CMTATStandaloneAllowlist.sol
 │   │   └── CMTATUpgradeableAllowlist.sol
-│   ├── CMTATStandalone.sol
-│   ├── CMTATUpgradeable.sol
+│   ├── CMTATStandardStandalone.sol
+│   ├── CMTATStandardUpgradeable.sol
 │   ├── CMTATUpgradeableUUPS.sol
 │   ├── debt
 │   │   ├── CMTATStandaloneDebt.sol
@@ -21,15 +21,15 @@ contracts
 │   ├── holderList
 │   │   ├── CMTATStandaloneHolderList.sol
 │   │   └── CMTATUpgradeableHolderList.sol
+│   ├── light
+│   │   ├── CMTATStandaloneLight.sol
+│   │   └── CMTATUpgradeableLight.sol
 │   ├── permit
 │   │   ├── CMTATStandalonePermit.sol
 │   │   └── CMTATUpgradeablePermit.sol
-│   ├── snapshot
-│   │   ├── CMTATStandaloneSnapshot.sol
-│   │   └── CMTATUpgradeableSnapshot.sol
-│   └── light
-│       ├── CMTATStandaloneLight.sol
-│       └── CMTATUpgradeableLight.sol
+│   └── snapshot
+│       ├── CMTATStandaloneSnapshot.sol
+│       └── CMTATUpgradeableSnapshot.sol
 ├── interfaces
 │   ├── engine
 │   │   ├── IDebtEngine.sol
@@ -41,6 +41,7 @@ contracts
 │   │   ├── IDebtEngineModule.sol
 │   │   ├── IDebtModule.sol
 │   │   ├── IDocumentEngineModule.sol
+│   │   ├── IHolderListModule.sol
 │   │   └── ISnapshotEngineModule.sol
 │   ├── technical
 │   │   ├── ICMTATConstructor.sol
@@ -55,15 +56,18 @@ contracts
 │       ├── draft-IERC1643.sol
 │       ├── draft-IERC7551.sol
 │       ├── draft-IERC7943.sol
+│       ├── draft-IERC8343.sol
 │       ├── ICMTAT.sol
 │       └── IERC3643Partial.sol
 ├── library
 │   ├── ERC1404ExtendInterfaceId.sol
 │   └── RuleEngineInterfaceId.sol
 ├── mocks
+│   ├── CMTATMsgDataMock.sol
 │   ├── DebtEngineMock.sol
 │   ├── DocumentEngineMock.sol
 │   ├── engine
+│   │   ├── CMTATDocumentEngineModuleMock.sol
 │   │   └── CMTATEngineInitializerMock.sol
 │   ├── ERC1363ReceiverMock.sol
 │   ├── ERC165Helper
@@ -82,76 +86,82 @@ contracts
 │   │   ├── CodeList.sol
 │   │   ├── interfaces
 │   │   │   ├── IRuleEngineMock.sol
-│   │   │   └── IRule.sol
+│   │   │   ├── IRule.sol
+│   │   │   └── IRuleTransferHook.sol
 │   │   ├── RuleEngineMock.sol
+│   │   ├── RuleEngineReentrantMock.sol
 │   │   ├── RuleMockMint.sol
-│   │   └── RuleMock.sol
+│   │   ├── RuleMock.sol
+│   │   ├── RuleSpenderAuthorized.sol
+│   │   └── RuleTokenHolderTracker.sol
 │   ├── SnapshotEngineMock.sol
 │   └── test
 │       └── proxy
 │           ├── CMTAT_PROXY_TEST.sol
 │           └── CMTAT_PROXY_TEST_UUPS.sol
-├── modules
-│   ├── 0_CMTATBaseCommon.sol
-│   ├── 0_CMTATBaseCore.sol
-│   ├── 0_CMTATBaseGeneric.sol
-│   ├── 0_CMTATBaseSnapshot.sol
-│   ├── 2_CMTATBaseAccessControl.sol
-│   ├── 3_CMTATBaseAllowlist.sol
-│   ├── 3_CMTATBaseRuleEngine.sol
-│   ├── 1_CMTATBaseDocument.sol
-│   ├── 4_CMTATBaseDebt.sol
-│   ├── 4_CMTATBaseERC1404.sol
-│   ├── 4_CMTATBaseERC20CrossChain.sol
-│   ├── 4_CMTATBaseERC2612.sol
-│   ├── 5_CMTATBaseDebtEngine.sol
-│   ├── 5_CMTATBaseERC2771.sol
-│   ├── 6_CMTATBaseERC2771Snapshot.sol
-│   ├── 6_CMTATBaseERC7551Enforcement.sol
-│   ├── 7_CMTATBaseERC1363.sol
-│   ├── 7_CMTATBaseERC7551.sol
-│   ├── 8_CMTATBaseHolderList.sol
-│   ├── internal
-│   │   ├── AllowlistModuleInternal.sol
-│   │   ├── common
-│   │   │   └── EnforcementModuleLibrary.sol
-│   │   ├── EnforcementModuleInternal.sol
-│   │   ├── ERC20BurnModuleInternal.sol
-│   │   ├── ERC20EnforcementModuleInternal.sol
-│   │   ├── ERC20MintModuleInternal.sol
-│   │   └── ValidationModuleRuleEngineInternal.sol
-│   └── wrapper
-│       ├── controllers
-│       │   ├── ValidationModuleAllowlist.sol
-│       │   └── ValidationModule.sol
-│       ├── core
-│       │   ├── EnforcementModule.sol
-│       │   ├── ERC20BaseModule.sol
-│       │   ├── ERC20BurnModule.sol
-│       │   ├── ERC20MintModule.sol
-│       │   ├── PauseModule.sol
-│       │   ├── TokenAttributeModule.sol
-│       │   ├── ValidationModuleCore.sol
-│       │   └── VersionModule.sol
-│       ├── extensions
-│       │   ├── DocumentEngineModule.sol
-│       │   ├── ERC20EnforcementModule.sol
-│       │   ├── ExtraInformationModule.sol
-│       │   ├── SnapshotEngineModule.sol
-│       │   └── ValidationModule
-│       │       ├── ValidationModuleAllowance.sol
-│       │       ├── ValidationModuleERC1404.sol
-│       │       └── ValidationModuleRuleEngine.sol
-│       ├── options
-│       │   ├── AllowlistModule.sol
-│       │   ├── CCIPModule.sol
-│       │   ├── DebtEngineModule.sol
-│       │   ├── DebtModule.sol
-│       │   ├── ERC20CrossChainModule.sol
-│       │   ├── ERC20EnforcementERC7551Module.sol
-│       │   ├── ERC2771Module.sol
-│       │   ├── ERC7551Module.sol
-│       │   └── HolderListModule.sol
-│       └── security
-│           └── AccessControlModule.sol
-33 directories, 110 files
+└── modules
+    ├── 0_CMTATBaseCommon.sol
+    ├── 0_CMTATBaseCore.sol
+    ├── 0_CMTATBaseGeneric.sol
+    ├── 0_CMTATBaseSnapshot.sol
+    ├── 1_CMTATBaseDocument.sol
+    ├── 2_CMTATBaseAccessControl.sol
+    ├── 3_CMTATBaseAllowlist.sol
+    ├── 3_CMTATBaseRuleEngine.sol
+    ├── 4_CMTATBaseDebt.sol
+    ├── 4_CMTATBaseERC1404.sol
+    ├── 5_CMTATBaseERC20CrossChain.sol
+    ├── 6_CMTATBaseDebtEngine.sol
+    ├── 6_CMTATBaseERC2612.sol
+    ├── 6_CMTATBaseERC2771.sol
+    ├── 7_CMTATBaseERC2771Snapshot.sol
+    ├── 7_CMTATBaseERC7551Enforcement.sol
+    ├── 8_CMTATBaseERC1363.sol
+    ├── 8_CMTATBaseERC7551.sol
+    ├── 8_CMTATBaseHolderList.sol
+    ├── internal
+    │   ├── AllowlistModuleInternal.sol
+    │   ├── common
+    │   │   └── EnforcementModuleLibrary.sol
+    │   ├── EnforcementModuleInternal.sol
+    │   ├── ERC20BurnModuleInternal.sol
+    │   ├── ERC20EnforcementModuleInternal.sol
+    │   ├── ERC20MintModuleInternal.sol
+    │   └── ValidationModuleRuleEngineInternal.sol
+    └── wrapper
+        ├── controllers
+        │   ├── ValidationModuleAllowlist.sol
+        │   └── ValidationModule.sol
+        ├── core
+        │   ├── EnforcementModule.sol
+        │   ├── ERC20BaseModule.sol
+        │   ├── ERC20BurnModule.sol
+        │   ├── ERC20MintModule.sol
+        │   ├── PauseModule.sol
+        │   ├── TokenAttributeModule.sol
+        │   ├── ValidationModuleCore.sol
+        │   └── VersionModule.sol
+        ├── extensions
+        │   ├── DocumentERC1643Module.sol
+        │   ├── ERC20EnforcementModule.sol
+        │   ├── ExtraInformationModule.sol
+        │   ├── SnapshotEngineModule.sol
+        │   └── ValidationModule
+        │       ├── ValidationModuleAllowance.sol
+        │       ├── ValidationModuleERC1404.sol
+        │       └── ValidationModuleRuleEngine.sol
+        ├── options
+        │   ├── AllowlistModule.sol
+        │   ├── CCIPModule.sol
+        │   ├── DebtEngineModule.sol
+        │   ├── DebtModule.sol
+        │   ├── DocumentEngineModule.sol
+        │   ├── ERC20CrossChainModule.sol
+        │   ├── ERC20EnforcementERC7551Module.sol
+        │   ├── ERC2771Module.sol
+        │   ├── ERC7551Module.sol
+        │   └── HolderListModule.sol
+        └── security
+            └── AccessControlModule.sol
+
+35 directories, 129 files

.claude/tree/test_tree.txt

@@ -16,13 +16,15 @@ test
 │   ├── ERC20BaseModuleCommon.js
 │   ├── ERC20BurnModuleCommon.js
 │   ├── ERC20CrossChainModuleCommon.js
+│   ├── ERC20EnforcementERC7551ModuleCommon.js
 │   ├── ERC20EnforcementModuleCommon.js
 │   ├── ERC20MintModuleCommon.js
 │   ├── ERC7551ModuleCommon.js
 │   ├── ExtraInfoModuleCommon.js
 │   ├── HolderListModuleCommon.js
-│   ├── MulticallModuleCommon.js
 │   ├── MetaTxModuleCommon.js
+│   ├── MetaTxMsgDataCommon.js
+│   ├── MulticallModuleCommon.js
 │   ├── PauseModuleCommon.js
 │   ├── PermitModuleCommon.js
 │   ├── SnapshotModuleCommon
@@ -42,6 +44,7 @@ test
 │   ├── ValidationModule
 │   │   ├── proxy
 │   │   │   └── ValidationModuleProxyCommon.js
+│   │   ├── RuleEngineReentrancyCommon.js
 │   │   ├── ValidationModuleCommonCore.js
 │   │   ├── ValidationModuleCommon.js
 │   │   └── ValidationModuleSetRuleEngineCommon.js
@@ -57,7 +60,7 @@ test
 │   │   ├── deploymentUpgradeableDebtSnapshot.test.js
 │   │   └── deploymentUpgradeableDebt.test.js
 │   ├── debtEngine
-│   │   ├── deploymentStandaloneDebtEngineSnapshot.test .js
+│   │   ├── deploymentStandaloneDebtEngineSnapshot.test.js
 │   │   ├── deploymentStandaloneDebtEngine.test.js
 │   │   └── deploymentUpgradeableDebtEngine.test.js
 │   ├── deployment.test.js
@@ -71,12 +74,15 @@ test
 │   ├── erc7551
 │   │   ├── deploymentERC7551Standalone.test.js
 │   │   └── deploymentERC7551Upgradeable.test.js
+│   ├── light
+│   │   ├── deploymentStandaloneLight.test.js
+│   │   └── deploymentUpgradeableLight.test.js
 │   ├── permit
 │   │   ├── deploymentPermitStandalone.test.js
 │   │   └── deploymentPermitUpgradeable.test.js
-│   └── light
-│       ├── deploymentStandaloneLight.test.js
-│       └── deploymentUpgradeableLight.test.js
+│   └── snapshot
+│       ├── deploymentStandaloneSnapshot.test.js
+│       └── deploymentUpgradeableSnapshot.test.js
 ├── deploymentUtils.js
 ├── proxy
 │   ├── general
@@ -104,6 +110,7 @@ test
 │       ├── SnapshotModule
 │       │   └── SnapshotModule.test.js
 │       ├── ValidationModule
+│       │   ├── ValidationModuleReentrancy.test.js
 │       │   └── ValidationModule.test.js
 │       └── VersionModule.test.js
 ├── standard
@@ -112,6 +119,8 @@ test
 │       │   └── AuthorizationModule.test.js
 │       ├── CCIPModule.test.js
 │       ├── CMTATIntegration.test.js
+│       ├── DocumentEngineModule
+│       │   └── DocumentEngineModule.test.js
 │       ├── DocumentModule
 │       │   └── DocumentModule.test.js
 │       ├── EnforcementModule.test.js
@@ -126,14 +135,20 @@ test
 │       ├── MetaTxModuleERC1363.test.js
 │       ├── MetaTxModule.test.js
 │       ├── MetaTxModuleUUPS.test.js
+│       ├── MetaTxMsgDataAllowlist.test.js
+│       ├── MetaTxMsgDataERC1363.test.js
+│       ├── MetaTxMsgDataSnapshot.test.js
+│       ├── MetaTxMsgData.test.js
 │       ├── PauseModule.test.js
+│       ├── RuleEngineMockStatefulRule.test.js
 │       ├── SnapshotModule
 │       │   └── SnapshotModule.test.js
 │       ├── ValidationModule
 │       │   ├── ValidationModuleConstructor.test.js
+│       │   ├── ValidationModuleReentrancy.test.js
 │       │   ├── ValidationModuleSetRuleEngine.test.js
 │       │   └── ValidationModule.test.js
 │       └── VersionModule.test.js
 └── utils.js
 
-30 directories, 101 files
+33 directories, 118 files

AGENTS.md

@@ -81,6 +81,18 @@ npm run coverage              # Generate coverage report
 npm run hardhat:compile       # Compile contracts
 ```
 
+## Test Catalogue
+
+The test suite is catalogued per feature module and per deployment version in **[doc/test/Test.md](doc/test/Test.md)**
+— a hand-maintained map whose purpose is to make **missing tests easy to find**.
+
+**Whenever you add, change or remove a test, update `doc/test/Test.md` in the same change:**
+- test added → adjust the module's `it` count / scenario, and add a matrix row or column if it covers a new feature or variant;
+- test removed → remove it, and note any resulting coverage gap;
+- new deployment variant or shared test module → add the corresponding matrix column / row and module-reference entry.
+
+An out-of-date catalogue is worse than none — keep it in sync.
+
 ## Test Troubleshooting
 
 If tests fail with gas reporter / Mocha reporter errors (for example `ERR_MOCHA_INVALID_REPORTER` with `eth-gas-reporter`), run tests with gas reporting disabled:
@@ -99,6 +111,31 @@ DeactivateReportGas=true npx hardhat test
 - `hardhat.config.js` - Build configuration (EVM & Solidity version)
 - `package.json` - Dependencies and scripts
 
+## Documentation Lookup
+
+Before stating that something is **not documented**, search **all** of the documentation surfaces below. They
+overlap and none of them is authoritative on its own — a rationale is often recorded in one place and the
+per-function facts in another.
+
+| Surface | What lives there |
+| --- | --- |
+| `doc/README.md` | The largest document. Standards mapping (ERC-3643, ERC-7943, ERC-7551, ERC-7802), architecture, module list, access control, engines, and the **Enforcement / Transfer restriction** chapter — including behavioural rationales such as why pause does not block issuer mint/burn. |
+| `doc/USAGE.md` | Build, test, deploy and tooling instructions. |
+| `doc/modules/**` | Per-module reference pages (`core/`, `extensions/`, `options/`, `controllers/`), one per module, with per-function requirements, events and errors. |
+| `doc/technical/**` | Cross-cutting topics: `access-control.md`, `cross-chain-bridge-integration.md`, `deployment.md`, `upgradeable.md`, `stablecoin.md`, ERC-specific notes. |
+| `doc/SUMMARY.md` | Short index of modules, deployment variants and roles. |
+| `doc/security/**` | Audit reports and maintainer feedback. |
+| `contracts/**` NatSpec + inline comments | Design rationales are frequently recorded only in code comments (e.g. the `onlyTokenBridge` `msg.sender` justification). |
+
+Practical rule: grep the whole `doc/` tree **and** `contracts/`, not a subset.
+
+```bash
+grep -rn -i "<topic>" doc/ contracts/ --include=*.md --include=*.sol | grep -v doc/hardhat-compilation
+```
+
+Exclude `doc/hardhat-compilation/` (flattened build artifacts, including vendored OpenZeppelin comments) — matches
+there are **not** CMTAT statements and must not be quoted as project documentation.
+
 ## Note
 
 After each implemented feature or fix, provide a one-line GitHub commit message for all changes since the last commit.