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:

```bash
# 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:

```python
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:

```python
# 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:

```bash
# 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

```bash
# 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:
```bash
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](PLATFORM_SKILLS.md) - All available platform skills
- [ARCHITECTURE.md](ARCHITECTURE.md) - How the bot works
- [Mastodon API - Update Credentials](https://docs.joinmastodon.org/methods/accounts/#update_credentials)
- [Mastodon API - Pin Status](https://docs.joinmastodon.org/methods/statuses/#pin)