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>
Applied "Single Source of Truth with Contextual Pointers" pattern:
README.md changes:
- Simplified "Security Note" section to brief warning + bullets
- Removed detailed file list (now only in SECURITY.md)
- Kept inline warning in Quick Start (contextual, at point of use)
- Added bullets describing what SECURITY.md covers
- Result: Brief, clear, points to authoritative source
Documentation strategy:
- SECURITY.md = single source of truth (all details)
- Other docs = brief inline warnings + links to SECURITY.md
- Inline warnings kept at critical moments (e.g., creating config.yaml)
- Platform-specific notes stay in platform guides
Added .maintenance-notes.md:
- Documents the documentation strategy
- Explains what goes where and why
- Provides guidance for future updates
- Helps prevent redundancy creep
Benefits:
- Easier to maintain (update SECURITY.md, others just link)
- Still highly visible (warnings at critical steps)
- No loss of information (everything in SECURITY.md)
- Clear ownership (each file owns specific info)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Updated README.md:
- Added prominent security warning about config.yaml containing secrets
- Clarified that config.yaml is gitignored and never committed
- Added step-by-step Quick Start with security notes
- Added "Security Note" section listing protected files
- Added Documentation section linking to all guides including SECURITY.md
- Added note about API keys stored in ~/.llm/keys.json
Updated QUICKSTART.md:
- Added security warning box when copying config.yaml
- Explained that file contains secrets and is gitignored
- Added reference to SECURITY.md for complete guidance
Updated MASTODON_SETUP.md:
- Added prominent link to SECURITY.md at top of Security Considerations
- Clarified that credential files are gitignored
- Added note about *_clientcred.secret and *_usercred.secret files
All documentation now clearly explains:
- Where secrets go (config.yaml, ~/.llm/keys.json)
- What's protected by .gitignore
- Where to find complete security information (SECURITY.md)
- How to safely configure the bot
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Govbot is an AI-powered governance bot that interprets natural language
constitutions and facilitates collective decision-making across social
platforms.
Core features:
- Agentic architecture with constitutional reasoning (RAG)
- Platform-agnostic design (Mastodon, Discord, Telegram, etc.)
- Action primitives for flexible governance processes
- Temporal awareness for multi-day proposals and voting
- Audit trail with constitutional citations
- Reversible actions with supermajority veto
- Works with local (Ollama) and cloud AI models
Platform support:
- Mastodon: Full implementation with streaming, moderation, and admin skills
- Discord/Telegram: Platform abstraction ready for implementation
Documentation:
- README.md: Architecture and overview
- QUICKSTART.md: Getting started guide
- PLATFORMS.md: Platform implementation guide for developers
- MASTODON_SETUP.md: Complete Mastodon deployment guide
- constitution.md: Example governance constitution
Technical stack:
- Python 3.11+
- SQLAlchemy for state management
- llm CLI for model abstraction
- Mastodon.py for Mastodon integration
- Pydantic for configuration validation
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
