agentic-govbot/CONSTITUTION_PUBLISHING.md

Constitution Publishing

The bot can publish and maintain its constitution as a pinned thread on Mastodon, creating a transparent, versioned record of governance rules.

How It Works

Constitutional Version Control

When you publish or update the constitution:

1. Previous Version Deprecated: The old pinned constitution gets a deprecation notice
2. New Version Posted: Constitution is split into a thread (~450 chars per post)
3. Thread Pinned: First post is pinned to the bot's profile
4. History Preserved: Old versions remain visible with deprecation notices
5. ID Tracked: Post ID saved to config/.constitution_post_id for future updates

Thread Format

📜 CONSTITUTION (Updated: 2026-02-10)

Thread 🧵 [1/5]

[Constitution content...]

[2/5]
[More content...]

[3/5]
[More content...]

Deprecation Notice (on old versions)

⚠️ DEPRECATED: This constitution has been superseded.

Changes: Updated voting thresholds and added new roles

Please see my profile for the current pinned constitution.

Publishing Methods

Method 1: Via Bot Command (Recommended)

Ask the bot directly via Mastodon:

@govbot please publish the current constitution

The bot will:

• Read constitution.md
• Check authority per constitution
• Post and pin the thread
• Report success/failure

Method 2: Helper Script

Use the provided script for direct publishing:

# Basic usage
python scripts/publish_constitution.py

# With change summary
python scripts/publish_constitution.py --summary "Added role-based permissions"

# Custom constitution file
python scripts/publish_constitution.py --constitution docs/governance.md

# Full options
python scripts/publish_constitution.py \
  --constitution constitution.md \
  --summary "Updated voting thresholds" \
  --config config/config.yaml

Script options:

• --summary / -s: Description of changes (shown in deprecation notice)
• --constitution / -c: Path to constitution file (default: constitution.md)
• --config: Path to config file (default: config/config.yaml)

Method 3: Python API

Programmatically publish from your own code:

from src.govbot.utils.config import load_config
from src.govbot.platforms.mastodon import MastodonAdapter

# Load config and connect
config = load_config("config/config.yaml")
adapter = MastodonAdapter(config.platform.mastodon.model_dump())
adapter.connect()

# Publish constitution
result = adapter.execute_skill(
    skill_name="publish_constitution",
    parameters={
        "constitution_text": constitution_text,
        "change_summary": "What changed in this version",
    },
    actor="@admin"
)

print(result["message"])

Profile Integration

Update Profile to Reference Constitution

The bot can also update its profile to highlight the constitution:

# Via bot command
@govbot update your profile to mention the constitution in your bio

# Via Python API
adapter.execute_skill(
    skill_name="update_profile",
    parameters={
        "display_name": "Govbot",
        "note": "🤖 Governance bot for democratic communities.\n\n📜 Constitution pinned to profile.",
        "fields": [
            {"name": "Constitution", "value": "📜 See pinned post"},
            {"name": "Governance", "value": "Consensus-based"},
            {"name": "Source Code", "value": "github.com/you/repo"},
            {"name": "Contact", "value": "@admin"}
        ]
    },
    actor="@admin"
)

Profile fields appear as a table on the bot's profile page.

Best Practices

Initial Publication

When first setting up the bot:

1. Finalize Constitution: Make sure constitution.md is complete
2. Set Profile: Update bio and fields to reference constitution
3. Publish Constitution: Run publish script or ask bot
4. Verify: Visit bot's profile to confirm pinned thread

Updating Constitution

When making changes:

1. Edit File: Update constitution.md with changes
2. Write Summary: Prepare clear description of what changed
3. Test Locally: Use CLI mode to test if needed
4. Publish Update: Run script with --summary flag
5. Verify: Check that:
   • Old version has deprecation notice
   • New version is pinned
   • Profile still references constitution

Version Control

Consider maintaining constitution in git:

# Track changes
git add constitution.md
git commit -m "Update voting thresholds from 60% to 66%"

# Publish to Mastodon
python scripts/publish_constitution.py \
  --summary "Update voting thresholds from 60% to 66%"

# Push to repo
git push

This gives you:

• Git history: Full version control with diffs
• Mastodon thread history: Public, timestamped versions
• Deprecation chain: Links between versions

Example Workflow

Scenario: Updating Voting Rules

# 1. Edit constitution
nano constitution.md
# (Change "50% majority" to "60% supermajority")

# 2. Test understanding (optional)
python -m src.govbot.governance.constitution "What is the voting threshold?"
# Verify it understands the new rule

# 3. Commit to git
git add constitution.md
git commit -m "Increase voting threshold to supermajority"

# 4. Publish to Mastodon
python scripts/publish_constitution.py \
  --summary "Increased voting threshold from 50% to 60%"

# Output:
# 📜 Loaded constitution from constitution.md (4532 chars)
# 🔌 Connecting to https://govbot.modpol.net...
# ✅ Connected as @govbot
# 📤 Publishing constitution...
#    Change summary: Increased voting threshold from 50% to 60%
# ✅ Constitution published as 8-post thread and pinned to profile.
#    Previous version marked as deprecated.
# 📊 Details:
#    - Thread length: 8 posts
#    - First post ID: 123456789
#    - Previous post ID: 123456700 (deprecated)
# 🔗 View at: https://govbot.modpol.net/@govbot
# ✨ Done!

# 5. Verify
# Visit https://govbot.modpol.net/@govbot
# - New thread is pinned
# - Old thread has deprecation notice

Technical Details

File Storage

The current constitution post ID is stored in:

config/.constitution_post_id

This file is gitignored but tracked by the bot to find the previous version when updating.

Thread Splitting Algorithm

The bot splits constitution into chunks:

1. Split by paragraphs: Preserves semantic boundaries
2. Combine into chunks: Up to 450 chars each (leaving room for thread indicators)
3. Add thread indicators: [1/8], [2/8], etc.
4. First post header: Includes emoji, date, and thread indicator
5. Post sequentially: Each replies to the previous

Post Visibility

Constitution posts are always:

• Public visibility: Anyone can see and share
• Threaded: Each post replies to previous
• Pinned: First post pinned to profile (max 5 pins)

Mastodon API Requirements

Publishing requires:

• write:accounts scope (for pinning/unpinning)
• write:statuses scope (for posting)
• Bot must be connected and authenticated

Troubleshooting

"Failed to pin constitution"

Cause: Too many posts already pinned (max 5)

Solution: Manually unpin old posts from web interface at Settings → Profile → Pinned posts

"Constitution file not found"

Cause: File path incorrect

Solution: Verify file exists:

ls -la constitution.md

"Not authorized to publish"

Cause: Bot doesn't have authority per constitution

Solution: Either:

• Grant bot authority in constitution
• Use script directly (bypasses authorization check)

"Previous version not found"

Cause: .constitution_post_id file missing or contains invalid ID

Solution:

• First publication: This is normal, ignore
• Subsequent: Old version won't be deprecated (but new version will still pin)

Future Enhancements

Potential improvements:

• Diff Display: Show exact changes between versions
• Amendment Tracking: Link to governance processes that authorized changes
• Multilingual: Publish translations as separate threads
• Rich Formatting: Use custom emojis or instance-specific formatting
• Automatic Publishing: Trigger on git push or governance process completion

See Also

• PLATFORM_SKILLS.md - All available platform skills
• ARCHITECTURE.md - How the bot works
• Mastodon API - Update Credentials
• Mastodon API - Pin Status