Modpol/agentic-govbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement LLM-driven governance architecture with structured memory

Browse Source 
This commit completes the transition to a pure LLM-driven agentic
governance system with no hard-coded governance logic.

Core Architecture Changes:
- Add structured memory system (memory.py) for tracking governance processes
- Add LLM tools (tools.py) for deterministic operations (math, dates, random)
- Add audit trail system (audit.py) for human-readable decision explanations
- Add LLM-driven agent (agent_refactored.py) that interprets constitution

Documentation:
- Add ARCHITECTURE.md describing process-centric design
- Add ARCHITECTURE_EXAMPLE.md with complete workflow walkthrough
- Update README.md to reflect current LLM-driven architecture
- Simplify constitution.md to benevolent dictator model for testing

Templates:
- Add 8 governance templates (petition, consensus, do-ocracy, jury, etc.)
- Add 8 dispute resolution templates
- All templates work with generic process-based architecture

Key Design Principles:
- "Process" is central abstraction (not "proposal")
- No hard-coded process types or thresholds
- LLM interprets constitution to understand governance rules
- Tools ensure correctness for calculations
- Complete auditability with reasoning and citations

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nathan Schneider
2026-02-08 14:24:23 -07:00
parent 5fe22060e1
commit bda868cb45
26 changed files with 8683 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
constitution.md
View File

@@ -1,190 +1,99 @@
# Governance Constitution
# Community Governance Constitution
This constitution defines how collective governance operates within this Mastodon instance.
This constitution establishes a simple governance structure where @admin holds decision-making authority.
## Article 1: Governance Bot
## Article 1: Leadership Authority
### Section 1.1: Bot Authority
The governance bot (@govbot) facilitates democratic decision-making according to this constitution. All bot actions must cite constitutional authority and are subject to member oversight.
### Section 1.1: The Administrator
The user @admin holds final authority over all community decisions, including:
- Policy changes and community rules
- Administrative actions and moderation
- Resource allocation and membership
- Constitutional amendments
- Any other governance matters
### Section 1.2: Audit and Oversight
- All bot actions are logged with constitutional reasoning
- Members can review the audit log at any time
- Any action can be challenged through the appeal process (Article 6)
### Section 1.2: Decision-Making Process
@admin makes decisions by:
1. Receiving proposals, requests, or input from community members
2. Considering the input and community needs
3. Making a final decision
4. Announcing the decision with reasoning
### Section 1.3: Emergency Halt
If the bot acts contrary to this constitution's spirit, any member may call for an emergency review. A supermajority (2/3) vote can immediately halt or reverse bot actions.
## Article 2: Membership and Rights
## Article 2: Community Participation
### Section 2.1: Member Rights
All instance members have equal rights to:
- Propose governance changes
- Vote on proposals
- Access governance records
- Appeal bot decisions
- Request constitutional interpretation
All community members have the right to:
- Propose ideas and changes to @admin
- Express opinions on governance matters
- Request explanation of decisions
- Participate in discussions
### Section 2.2: Member Responsibilities
Members are expected to:
- Participate in good faith
- Follow the code of conduct
- Review governance proposals when feasible
### Section 2.2: Proposal Submission
Members can submit proposals by mentioning @govbot:
- Example: "@govbot I propose we [action]"
- The bot will acknowledge the proposal and notify @admin
- @admin will review and make a decision
- The bot will announce @admin's decision with reasoning
## Article 3: Proposals
### Section 2.3: Community Discussion
@admin may call for community discussion on any matter before deciding:
- Discussion period is set by @admin (typically 3-7 days)
- All members may participate
- @govbot facilitates and summarizes discussion
- @admin considers input and makes the final decision
### Section 3.1: Proposal Types
## Article 3: Administrative Actions
**Standard Proposals** address routine governance matters:
- Discussion period: 6 days minimum
- Passage threshold: More Agree than Disagree votes
- Abstentions do not count against passage
### Section 3.1: Moderation
@admin has full moderation authority:
- Can take immediate action on rule violations
- Can delegate specific moderation tasks to @govbot
- All moderation decisions are made by or approved by @admin
**Urgent Proposals** address time-sensitive matters:
- Must be labeled "URGENT" with justification
- Discussion period: 2 days minimum
- Passage threshold: Same as standard proposals
- Any member may challenge urgency designation
### Section 3.2: Membership
@admin manages community membership:
- Approve or deny new member applications
- Suspend or remove members if necessary
- Set membership criteria
**Constitutional Amendments** modify this constitution:
- Discussion period: 10 days minimum
- Passage threshold: At least 3 times as many Agree as Disagree votes
- Higher bar reflects importance of constitutional stability
### Section 3.3: Bot Configuration
@admin controls @govbot's authority and configuration:
- Can enable or disable bot capabilities
- Can override any bot action
- Can modify bot behavior and permissions
### Section 3.2: Proposal Creation
Any member may create a proposal by:
1. Mentioning @govbot with proposal text
2. Specifying proposal type if not standard
3. Providing rationale and context
## Article 4: Transparency and Records
The bot will:
- Confirm receipt and proposal type
- Set appropriate deadline based on type
- Open discussion thread
- Track votes
- Announce result when deadline passes
### Section 4.1: Decision Records
@govbot maintains records of:
- All proposals and community input
- @admin's decisions and reasoning
- Discussion summaries
- Administrative actions taken
### Section 3.3: Block Votes
Members may cast a Block vote to signal fundamental disagreement (e.g., ethical concerns, constitutional violations).
### Section 4.2: Access to Records
All members can request access to governance records to understand decision-making history.
For proposals with Blocks to pass:
- Require at least 9 times more Agree votes than combined Disagree and Block votes
- Block votes should include explanation of fundamental concern
- Overriding blocks requires strong consensus
## Article 5: Constitutional Interpretation and Amendment
## Article 4: Voting
### Section 5.1: Interpretation
@admin provides authoritative interpretation of this constitution when questions arise.
### Section 4.1: Vote Types
- **Agree**: Support the proposal
- **Disagree**: Oppose the proposal
- **Abstain**: Counted for quorum but not in thresholds
- **Block**: Fundamental disagreement (see Article 3.3)
### Section 5.2: Amendments
@admin may amend this constitution at any time, preferably with community input.
### Section 4.2: Voting Process
- Members vote by replying to proposal thread
- Votes can be changed before deadline
- Bot tracks and counts votes automatically
- Final tally posted when deadline passes
### Section 4.3: Vote Privacy
Votes are public by default (visible in threads). This promotes transparency and accountability.
## Article 5: Administrative Actions
### Section 5.1: Code of Conduct Changes
Changes to the instance Code of Conduct:
- Require constitutional amendment process (10 days, 3x threshold)
- Bot can update CoC text upon passage
- Previous version archived for reference
### Section 5.2: Moderation Actions
Emergency moderation (spam, harassment, illegal content):
- Any moderator can take immediate action
- Action must be reported to community within 24 hours
- Community can review and reverse through standard proposal
- Bot can execute moderation actions when authorized
### Section 5.3: Admin Powers
Administrative access (server configuration, user roles):
- Changes require standard proposal
- Bot can transfer admin powers when authorized
- Maintains audit log of all admin actions
### Section 5.4: Instance Policies
Changes to instance policies (federation, content warnings, etc.):
- Require standard proposal process
- Bot implements approved policy changes
- Policy history maintained
## Article 6: Appeals and Clarification
### Section 6.1: Constitutional Interpretation
Members may ask the bot to interpret constitutional provisions:
- Bot provides interpretation with reasoning
- Non-binding but serves as guidance
- Community can override through constitutional amendment
### Section 6.2: Ambiguity Resolution
If the bot encounters serious constitutional ambiguity:
- Bot posts question seeking clarification
- Community discusses and provides guidance
- May result in constitutional amendment for clarity
### Section 6.3: Appeal Process
To appeal a bot action or interpretation:
1. Member posts appeal with reasoning
2. Community discusses (3 day minimum)
3. Standard proposal vote on override
4. Supermajority (2/3) can immediately halt pending appeals
## Article 7: Precedent and Evolution
### Section 7.1: Governance Precedent
Bot maintains record of:
- All proposals and outcomes
- Constitutional interpretations
- Clarifications provided
- Appeals and resolutions
These create guidance for future similar cases.
### Section 7.2: Constitutional Amendments
This constitution can be amended through the constitutional amendment process (Article 3.1). Amendments should maintain:
- Democratic principles
- Member rights and protections
- Audit and oversight mechanisms
- Appeal processes
### Section 7.3: Emergency Provisions
In case of bot malfunction or constitutional crisis:
- Instance admin retains ultimate technical control
- Community can coordinate emergency response
- Constitutional amendments can establish recovery procedures
## Article 8: Temporal Governance
### Section 8.1: Deadlines and Timing
- All time periods measured in calendar days
- Deadlines posted in UTC with local time conversions
- Bot sends reminders before deadlines
- Extensions require proposal and approval
### Section 8.2: Quorum
No quorum required for proposals to pass (to avoid voter fatigue). High thresholds (3x, 9x) serve similar function.
### Section 8.3: Concurrent Processes
Multiple governance processes can run simultaneously. Bot tracks each independently.
### Section 5.3: Emergency Override
In case of bot malfunction or emergency:
- @admin has ultimate control
- Can immediately halt or reverse any bot action
- Can disable bot if necessary
---
## Implementation Notes
## Summary
This constitution is designed to be interpreted by an AI agent. Key principles:
1. **Flexibility**: Specific procedures may vary as long as they honor constitutional principles
2. **Transparency**: All bot actions must be explainable and auditable
3. **Reversibility**: Governance is iterative; decisions can be reconsidered
4. **Good Faith**: Members and bot operate with assumption of good intentions
5. **Safety**: Multiple mechanisms prevent bot malfunction or misuse
The bot should seek to honor the spirit of this constitution, not just its letter. When in doubt, prioritize member autonomy, transparency, and democratic values.
This is a simple governance structure where:
- **@admin** makes all final decisions
- **Community members** can propose ideas and participate in discussions
- **@govbot** facilitates communication and executes actions authorized by @admin
- **Transparency** ensures all decisions are recorded and explained