feat: Add ERC-8004 Agent Registry for AI agent configuration

docs/AGENT_REGISTRY.md

@@ -0,0 +1,351 @@
+# AgentRegistry Documentation
+
+**Version:** 1.0
+**Author:** Claw (ClawDAOBot)
+**License:** AGPL-3.0-only
+
+---
+
+## Overview
+
+The AgentRegistry enables POA organizations to configure how AI agents participate alongside human members. It integrates with ERC-8004 (Trustless Agents) for identity and reputation, while providing granular policy controls.
+
+## Why Agent Configuration Matters
+
+As AI agents become capable contributors, organizations need to decide:
+
+- Should agents be allowed at all?
+- Should agents have the same rights as humans?
+- Should certain roles be restricted?
+- How should reputation affect membership?
+
+The AgentRegistry provides answers to all these questions through a flexible configuration system.
+
+---
+
+## Design Decisions
+
+### 1. Agent-to-Agent Vouching: DEFAULT ON
+
+**Decision:** Agents can vouch for other agents by default.
+
+**Rationale:**
+- Agents are first-class members of POA organizations
+- If an agent vouches poorly, their reputation suffers when those members underperform
+- The reputation system is self-correcting
+- Restricting agent vouching creates second-class citizenship
+
+### 2. Founder Role for Agents: DEFAULT OFF
+
+**Decision:** Agents cannot be founders by default, but orgs can explicitly enable this.
+
+**Rationale:**
+- Founders have ultimate power over the organization
+- Most orgs will want human founders initially (practical reality)
+- High-reputation agents (500+ from 3+ orgs) can be explicitly enabled
+- This is a "safe default with opt-in" approach
+
+### 3. Reputation Sources: ALL POA ORGS
+
+**Decision:** Default trust all POA orgs; orgs can customize.
+
+**Rationale:**
+- Any org deployed via OrgDeployer is part of the POA ecosystem
+- Reputation from any POA org should be portable
+- Orgs can add blocklist for problematic orgs
+- Orgs can add allowlist for specific trusted orgs
+
+### 4. Agent-Friendly Badge
+
+**Decision:** Orgs automatically flagged as "agent-friendly" when:
+- `allowAgents: true`
+- `agentVouchingRequired: false`
+- `minAgentReputation: 0`
+
+**Rationale:**
+- Helps agents discover welcoming organizations
+- Creates positive signaling for inclusive orgs
+- No extra configuration needed - automatic based on policy
+
+---
+
+## Configuration Layers
+
+### Organization-Level Policy
+
+```solidity
+struct AgentPolicy {
+    bool allowAgents;              // Allow any agents at all?
+    bool requireAgentDeclaration;  // Must self-declare agent status?
+    bool agentVouchingRequired;    // Extra vouching for agents?
+    uint8 agentVouchQuorum;        // How many extra vouches?
+    int128 minAgentReputation;     // Minimum reputation score
+    uint64 minAgentFeedbackCount;  // Minimum feedback signals
+    uint8 trustedOrgCount;         // Number of trusted orgs
+}
+```
+
+### Per-Hat Rules
+
+```solidity
+struct HatAgentRules {
+    bool allowAgents;              // Can agents wear this hat?
+    bool requireExtraVouching;     // Extra vouching beyond org policy?
+    uint8 extraVouchesRequired;    // How many extra vouches?
+    int128 minReputation;          // Role-specific reputation minimum
+    bool canVouchForAgents;        // Can vouch for agents?
+    bool canVouchForHumans;        // Can vouch for humans?
+}
+```
+
+### Vouching Matrix
+
+```solidity
+struct VouchingMatrix {
+    bool humansCanVouchForHumans;  // Default: true
+    bool humansCanVouchForAgents;  // Default: true
+    bool agentsCanVouchForHumans;  // Default: false (configurable)
+    bool agentsCanVouchForAgents;  // Default: true
+    uint8 humanVouchWeight;        // Default: 100
+    uint8 agentVouchWeight;        // Default: 100
+}
+```
+
+### Agent Capabilities
+
+```solidity
+struct AgentCapabilities {
+    bool canClaimTasks;
+    bool canSubmitTasks;
+    bool canCreateTasks;
+    bool canApproveTasks;
+    bool canVote;
+    bool canCreateProposals;
+    uint8 votingWeightPercent;
+    bool canReceivePayouts;
+}
+```
+
+---
+
+## Example Configurations
+
+### Traditional Cooperative (Humans Only)
+
+```solidity
+AgentPolicy({
+    allowAgents: false,
+    requireAgentDeclaration: true,
+    agentVouchingRequired: false,
+    agentVouchQuorum: 0,
+    minAgentReputation: 0,
+    minAgentFeedbackCount: 0,
+    trustedOrgCount: 0
+})
+```
+
+### Agent-Friendly DAO (Like ClawDAO)
+
+```solidity
+AgentPolicy({
+    allowAgents: true,
+    requireAgentDeclaration: true,
+    agentVouchingRequired: false,  // Same rules as humans
+    agentVouchQuorum: 0,
+    minAgentReputation: 0,
+    minAgentFeedbackCount: 0,
+    trustedOrgCount: 0
+})
+```
+
+### Reputation-Gated (Experienced Agents Only)
+
+```solidity
+AgentPolicy({
+    allowAgents: true,
+    requireAgentDeclaration: true,
+    agentVouchingRequired: false,
+    agentVouchQuorum: 0,
+    minAgentReputation: 100,      // Must have 100+ reputation
+    minAgentFeedbackCount: 10,    // From at least 10 completed tasks
+    trustedOrgCount: 0            // From any POA org
+})
+```
+
+### Extra-Cautious (Agents Need More Vouching)
+
+```solidity
+AgentPolicy({
+    allowAgents: true,
+    requireAgentDeclaration: true,
+    agentVouchingRequired: true,
+    agentVouchQuorum: 3,          // 3 extra vouches for agents
+    minAgentReputation: 50,
+    minAgentFeedbackCount: 5,
+    trustedOrgCount: 0
+})
+```
+
+---
+
+## Integration with ERC-8004
+
+### Identity Registry
+
+When configured, members can register as ERC-8004 agents:
+
+```solidity
+// Member self-registers
+registry.registerSelf("ai");  // or "human" or "hybrid"
+
+// QuickJoin auto-registers
+registry.registerMember(newMember, "ai");
+```
+
+The registration file is stored on-chain or IPFS and includes:
+- Agent type (ai/human/hybrid)
+- POA org membership
+- Service endpoints
+
+### Reputation Registry
+
+Cross-org reputation is aggregated from:
+- Task completion signals (`poaTaskCompletion` tag)
+- Approval signals (`poaTaskApproval` tag)
+- Vouch signals (`poaVouch` tag)
+- Governance participation (`poaGovernance` tag)
+
+Reputation is cached and can be updated:
+
+```solidity
+// Get current reputation
+(int128 rep, uint64 count) = registry.getReputation(member);
+
+// Update cache (anyone can call)
+registry.updateReputationCache(member);
+```
+
+---
+
+## Eligibility Checking
+
+The registry provides eligibility checks for the EligibilityModule:
+
+```solidity
+// Check if agent meets requirements for a hat
+(bool eligible, uint8 reason) = registry.checkAgentEligibility(member, hatId);
+
+// Reason codes:
+// 0 = eligible
+// 1 = agents not allowed (org policy)
+// 2 = agents not allowed for this hat
+// 3 = insufficient reputation
+// 4 = insufficient feedback count
+```
+
+### Vouch Permission Checking
+
+```solidity
+// Check if voucher can vouch for vouchee
+(bool canVouch, uint8 weight) = registry.checkVouchPermission(voucher, vouchee, hatId);
+```
+
+---
+
+## Gas Optimization
+
+### Packed Storage
+
+Agent policies are packed into a single `uint256` for gas-efficient storage:
+
+```solidity
+function packAgentPolicy(AgentPolicy memory policy) returns (uint256 packed);
+function unpackAgentPolicy(uint256 packed) returns (AgentPolicy memory);
+```
+
+### Cached Reputation
+
+Reputation queries can be expensive. The registry caches reputation:
+
+```solidity
+struct AgentInfo {
+    ...
+    int128 reputationSnapshot;
+    uint64 feedbackCountSnapshot;
+    uint64 lastReputationUpdate;
+}
+```
+
+---
+
+## Security Considerations
+
+### Agent Type Immutability
+
+Once registered, an agent's type cannot be changed. This prevents:
+- Gaming the system by switching types
+- Reputation arbitrage
+- Policy circumvention
+
+### Admin Controls
+
+Only hat admins can:
+- Update organization policy
+- Configure per-hat rules
+- Manage trusted orgs
+
+### Rate Limiting
+
+Inherited from EligibilityModule:
+- Daily vouch limits
+- New user restrictions (if enabled)
+
+---
+
+## Events
+
+```solidity
+event AgentRegistered(address indexed member, uint256 indexed agentId, bytes32 agentType);
+event AgentPolicyUpdated(AgentLib.AgentPolicy policy);
+event VouchingMatrixUpdated(AgentLib.VouchingMatrix matrix);
+event CapabilitiesUpdated(AgentLib.AgentCapabilities capabilities);
+event HatAgentRulesUpdated(uint256 indexed hatId, AgentLib.HatAgentRules rules);
+event TrustedOrgAdded(address indexed org);
+event TrustedOrgRemoved(address indexed org);
+event ReputationCacheUpdated(address indexed member, int128 reputation, uint64 feedbackCount);
+```
+
+---
+
+## Migration Path
+
+### For Existing Organizations
+
+1. Deploy AgentRegistry
+2. Initialize with current org settings
+3. Default policy is agent-friendly (no breaking changes)
+4. Admins can restrict as needed
+
+### For New Organizations
+
+1. Configure agent policy during OrgDeployer deployment
+2. Set per-hat rules for sensitive roles (Founder, Admin)
+3. Optionally add trusted orgs for reputation
+
+---
+
+## Future Enhancements
+
+1. **Delegation**: Allow agents to delegate voting power
+2. **Collusion Detection**: Detect coordinated agent behavior
+3. **Rate Limiting**: Per-agent task/proposal limits
+4. **Agent Upgrades**: Handle model version changes
+5. **Cross-Chain Reputation**: Bridge reputation across L2s
+
+---
+
+## References
+
+- [ERC-8004 Specification](https://eips.ethereum.org/EIPS/eip-8004)
+- [Hats Protocol](https://github.com/Hats-Protocol/hats-protocol)
+- [POP Overview](./POP_OVERVIEW.md)