tractatus/docs/outreach/SOCIAL-MEDIA-AND-HF-MAINTENANCE.md

# Social Media & Hugging Face Maintenance Guide

**Last Updated:** 2025-11-01
**Maintainer:** Claude Code instances
**Purpose:** Document social media presence and HF Space setup for future maintenance

---

## Table of Contents

1. [Reddit Presence](#reddit-presence)
2. [Facebook Presence](#facebook-presence)
3. [Hugging Face Space](#hugging-face-space)
4. [Deep Interlock Coordination Tracking](#deep-interlock-coordination-tracking)
5. [Maintenance Procedures](#maintenance-procedures)

---

## Reddit Presence

### Account Details

- **Username:** `tractatus-framework`
- **Display Name:** Tractatus Framework
- **Avatar:** `/home/theflow/projects/tractatus/public/images/tractatus-reddit-avatar.png` (512x512px)
- **Subreddit Target:** r/AI_Agents (primary), r/LangChain (secondary)
- **Purpose:** Share framework updates, engage with AI governance discussions

### Initial Posts

**First Post (r/AI_Agents - 2025-10-31):**
- **Title:** "Tractatus Framework: Open-source AI governance framework integrating Christopher Alexander's architectural principles"
- **Content:** Introduction to framework with key features:
  - 6 governance services (Deep Interlock coordination)
  - 5 Christopher Alexander principles for AI system design
  - Audit logging and transparency dashboard
  - MongoDB-based precedent tracking
  - Multi-language support (EN/DE/FR)
- **Links:**
  - Website: https://agenticgovernance.digital
  - Architecture: https://agenticgovernance.digital/architecture.html
  - Values: https://agenticgovernance.digital/about/values.html
  - GitHub: https://github.com/tractatus-framework (public repo)
  - HF Space: https://huggingface.co/spaces/tractatus-framework/audit-log-viewer

### Content Strategy

**Engagement Rules:**
1. **Build karma first:** Comment thoughtfully on 3-5 posts per day for 3-5 days before major link posts
2. **Avoid spam filters:**
   - Mix text-only discussions with link posts
   - Engage authentically, don't just promote
   - Wait 24-48 hours between promotional posts
3. **Target subreddits:**
   - r/AI_Agents (primary - AI agent development)
   - r/LangChain (technical discussions)
   - r/LocalLLaMA (self-hosted AI)
   - r/ArtificialIntelligence (broader discussions)

**Post Types:**
- Framework updates (new features, principles)
- Technical deep-dives (service architecture, coordination)
- Community questions (seek feedback on approach)
- Blog post shares (from `ridingthetiger.substack.com/chat`)

### Commenting Strategy

**Target Discussions:**
- Questions about AI agent governance
- Discussions on AI safety and alignment
- Technical questions about agent frameworks
- Posts about production AI deployments

**Tone:**
- Helpful and informative
- Cite framework documentation when relevant
- Acknowledge limitations and areas for improvement
- Focus on technical accuracy over promotion

### Known Issues

**Reddit Spam Filters:**
- Posts with links may be auto-removed initially
- **Solution:** Build account reputation through comments first
- If removed: Ask in r/AI_Agents modmail politely about visibility

---

## Facebook Presence

### Page Details

- **Page Name:** Agentic Governance NZ
- **URL:** To be determined (page creation in progress)
- **Purpose:** Share framework updates with NZ governance community
- **Target Audience:** NZ government, policy makers, AI practitioners

### Initial Post (Prepared)

**Content Focus:**
- Recent framework upgrades
- Integration of Christopher Alexander's 5 principles
- Emphasis on practical governance for AI agents

**Key URLs to Include:**
- Main site: https://agenticgovernance.digital
- Architecture page: https://agenticgovernance.digital/architecture.html
- Values page: https://agenticgovernance.digital/about/values.html
- GitHub: https://github.com/tractatus-framework

### Metadata Configuration

**Site Metadata for Social Sharing:**
Location: All public HTML files should have these meta tags (already implemented):

```html
<!-- Open Graph (Facebook) -->
<meta property="og:title" content="Tractatus Framework">
<meta property="og:description" content="Open-source AI governance framework">
<meta property="og:image" content="https://agenticgovernance.digital/images/tractatus-icon-new.svg">
<meta property="og:url" content="https://agenticgovernance.digital">
<meta property="og:type" content="website">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Tractatus Framework">
<meta name="twitter:description" content="Open-source AI governance framework">
<meta name="twitter:image" content="https://agenticgovernance.digital/images/tractatus-icon-new.svg">
```

**Facebook Link Metadata Issue:**
- Facebook shows "Link unavailable" for agenticgovernance.digital
- **Cause:** Site needs to be crawlable by Facebook's scraper
- **Solution:** Ensure proper Open Graph tags (already added to all pages)
- **Test:** Use Facebook Sharing Debugger: https://developers.facebook.com/tools/debug/

### Content Strategy

**Post Frequency:**
- Weekly updates on significant framework changes
- Monthly deep-dives on specific principles or services
- Ad-hoc posts for major milestones (new releases, blog posts)

**Post Types:**
- Framework updates (technical improvements)
- Principle explanations (Alexander's principles applied to AI)
- Case studies (real-world governance examples)
- Community engagement (questions, discussions)

---

## Hugging Face Space

### Space Details

- **Space Name:** `tractatus-framework/audit-log-viewer`
- **URL:** https://huggingface.co/spaces/tractatus-framework/audit-log-viewer
- **Type:** Gradio app (Python)
- **Purpose:** Public dashboard for framework audit log transparency

### Repository Structure

**Local Clone:** `~/audit-log-viewer/`

**Key Files:**
```
~/audit-log-viewer/
├── app.py                    # Gradio app (displays audit data)
├── audit-decisions.json      # Exported audit data (1.1 MB)
├── requirements.txt          # Python dependencies
├── README.md                # Space documentation
└── .git/                    # HF git repository
```

**Source Repository:** `/home/theflow/projects/tractatus/hf-space-deploy/`
- Contains initial setup files and deployment scripts

### App Features

**Visualization Components:**

1. **Dataset Statistics (Top Section):**
   - Total decisions count
   - Decisions by service (pie chart)
   - Decisions by outcome (allow/deny/ask)
   - Context pressure distribution
   - **Deep Interlock coordination metrics** (NEW)
     - Coordinated Decisions count
     - Single Service count
     - Coordination Rate percentage

2. **Interactive Table:**
   - Filterable by service, decision, date range
   - Sortable by all columns
   - Expandable coordination arrays
   - Pagination for large datasets

3. **Coordination Tracking (NEW - 2025-11-01):**
   - Shows which services coordinated on each decision
   - `coordination` field: array of service names
   - Example: `["BoundaryEnforcer", "ContextPressureMonitor"]`

### Data Export Process

**Export Script:** `scripts/export-hf-audit-data.js`

**Command:**
```bash
node scripts/export-hf-audit-data.js
```

**What it does:**
1. Connects to MongoDB (`tractatus_dev` database)
2. Queries `auditLogs` collection
3. Extracts coordination data from `metadata.services_involved`
4. Transforms to HF-compatible JSON format
5. Writes to `./audit-decisions.json` (1.1 MB)

**Output Format:**
```json
[
  {
    "timestamp": "2025-10-31T18:33:30.266Z",
    "action": "boundary_enforcement",
    "service": "BoundaryEnforcer",
    "decision": "allow",
    "boundary": "N/A",
    "boundary_domain": "TECHNICAL_IMPLEMENTATION",
    "context_pressure": "NORMAL",
    "coordination": ["BoundaryEnforcer", "ContextPressureMonitor"]
  }
]
```

**Statistics (as of 2025-11-01):**
- Total decisions: 3,942
- Coordinated decisions: 66
- Single service: 3,876
- **Coordination rate: 1.7%**

### Deployment Process

**1. Export fresh data:**
```bash
cd /home/theflow/projects/tractatus
node scripts/export-hf-audit-data.js
```

**2. Copy to HF Space repository:**
```bash
cp ./audit-decisions.json ~/audit-log-viewer/
```

**3. Commit and push:**
```bash
cd ~/audit-log-viewer
git add audit-decisions.json
git commit -m "feat: update audit data

- [Describe changes]
- [Statistics]

🤖 Generated with Claude Code"
git push
```

**4. HF Space auto-rebuilds:**
- Hugging Face detects the push
- Rebuilds the Gradio app automatically
- New data appears in ~2-3 minutes

### Authentication

**HF Token Location:** User provided during session: `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`
- **DO NOT commit this token to any repository**
- Token has write access to `tractatus-framework` organization spaces
- Used for: `git push` operations to HF Space

**Git Configuration:**
```bash
cd ~/audit-log-viewer
git remote -v
# origin  https://huggingface.co/spaces/tractatus-framework/audit-log-viewer (fetch)
# origin  https://huggingface.co/spaces/tractatus-framework/audit-log-viewer (push)
```

---

## Deep Interlock Coordination Tracking

### Problem Solved (2025-11-01)

**Initial Issue:**
- HF Space showed 0% coordination rate despite 6 services coordinating
- `services_involved` metadata was never populated in audit logs

**Root Cause:**
- `.claude/settings.local.json` overrode `.claude/settings.json`
- `framework-audit-hook.js` was excluded from PreToolUse hooks
- Only validator hooks (`validate-file-edit.js`, etc.) were running

### Implementation

**1. Fixed Hook Configuration**

File: `.claude/settings.local.json`

Added `framework-audit-hook.js` to PreToolUse hooks:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/framework-audit-hook.js",
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hook-validators/validate-file-edit.js"
          }
        ]
      }
      // ... other hooks
    ]
  }
}
```

**2. Coordination Tracking in Hook**

File: `.claude/hooks/framework-audit-hook.js`

Key changes:
- Line 284: Created `servicesInvolved` array
- Line 298: Passed array reference through `context.services_involved`
- Line 301: Push service name BEFORE calling (timing critical)
- Line 463: Track ContextPressureMonitor coordination

**Critical Pattern:**
```javascript
const servicesInvolved = [];  // Create tracking array

const context = {
  sessionId,
  tool: 'Edit/Write',
  file: filePath,
  services_involved: servicesInvolved  // Pass by reference
};

servicesInvolved.push('BoundaryEnforcer');  // BEFORE calling
const result = BoundaryEnforcer.enforce(action, context);
```

**Why timing matters:**
Services log audit entries immediately when called. If you push to the array AFTER calling, the array is empty when the service logs.

**3. Service Logging Updates**

**BoundaryEnforcer** (`src/services/BoundaryEnforcer.service.js:901`):
```javascript
metadata: {
  // ... other metadata
  services_involved: context.services_involved || []  // Deep Interlock tracking
}
```

**ContextPressureMonitor** (`src/services/ContextPressureMonitor.service.js:931`):
```javascript
metadata: {
  // ... other metadata
  services_involved: context.services_involved || []  // Deep Interlock tracking
}
```

### Testing Coordination Tracking

**Manual Test:**
```bash
# Test hook directly
echo '{"session_id":"test","hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/home/theflow/projects/tractatus/test.txt","old_string":"a","new_string":"b"}}' | .claude/hooks/framework-audit-hook.js
```

**Check Database:**
```bash
mongosh tractatus_dev --eval 'db.auditLogs.find({}, {_id:0, timestamp:1, service:1, "metadata.services_involved":1}).sort({timestamp: -1}).limit(5)'
```

**Expected Output:**
```javascript
[
  {
    service: 'ContextPressureMonitor',
    metadata: { services_involved: ['BoundaryEnforcer', 'ContextPressureMonitor'] },
    timestamp: ISODate('2025-10-31T18:33:30.270Z')
  },
  {
    service: 'BoundaryEnforcer',
    metadata: { services_involved: ['BoundaryEnforcer', 'ContextPressureMonitor'] },
    timestamp: ISODate('2025-10-31T18:33:30.266Z')
  }
]
```

### Coordination Statistics

**Current Metrics (2025-11-01):**
- Total decisions: 3,942
- Coordinated (2+ services): 66 (1.7%)
- Single service: 3,876 (98.3%)

**Why low coordination rate?**
1. Many operations are simple and don't require multiple services
2. Coordination happens when:
   - File modifications trigger BoundaryEnforcer + ContextPressureMonitor
   - Schema changes add CrossReferenceValidator
   - Complex operations add MetacognitiveVerifier
   - Governance files add InstructionPersistenceClassifier

**As framework usage grows:**
- More complex operations will increase coordination rate
- Multi-service decisions demonstrate Deep Interlock in action
- Target: 10-20% coordination rate for production systems

---

## Maintenance Procedures

### Weekly Maintenance

**1. Update HF Space Data (Every Monday)**

```bash
# Export fresh audit data
cd /home/theflow/projects/tractatus
node scripts/export-hf-audit-data.js

# Check statistics
python3 -c "
import json
with open('./audit-decisions.json', 'r') as f:
    data = json.load(f)
coordinated = sum(1 for d in data if len(d.get('coordination', [])) > 0)
total = len(data)
print(f'Total: {total}, Coordinated: {coordinated}, Rate: {coordinated/total*100:.1f}%')
"

# Copy to HF Space
cp ./audit-decisions.json ~/audit-log-viewer/

# Commit and push
cd ~/audit-log-viewer
git add audit-decisions.json
git commit -m "chore: weekly audit data update ($(date +%Y-%m-%d))

- Total decisions: [INSERT]
- Coordinated: [INSERT]
- Rate: [INSERT]%

🤖 Generated with Claude Code"
git push
```

**2. Reddit Engagement (Daily)**

```bash
# Check r/AI_Agents for relevant discussions
# Comment on 1-2 posts per day
# Focus on: governance questions, agent architecture, deployment challenges
```

**3. Facebook Posts (Weekly)**

```bash
# Share significant updates:
# - New framework features
# - Blog posts from ridingthetiger.substack.com
# - Coordination tracking improvements
# - Community milestones
```

### Monthly Maintenance

**1. Review Coordination Metrics**

```bash
# Analyze coordination trends
mongosh tractatus_dev --eval '
db.auditLogs.aggregate([
  { $match: { "metadata.services_involved": { $exists: true } } },
  { $group: {
      _id: { $month: "$timestamp" },
      total: { $sum: 1 },
      coordinated: {
        $sum: {
          $cond: [{ $gt: [{ $size: "$metadata.services_involved" }, 0] }, 1, 0]
        }
      }
    }
  },
  { $project: {
      month: "$_id",
      total: 1,
      coordinated: 1,
      rate: { $multiply: [{ $divide: ["$coordinated", "$total"] }, 100] }
    }
  },
  { $sort: { month: 1 } }
])'
```

**2. Content Planning**

- Review framework changelog
- Identify significant updates for social media
- Draft blog post topics for Substack
- Plan technical deep-dives for Reddit

**3. Community Engagement Review**

- Check Reddit post performance (upvotes, comments)
- Review Facebook page insights
- Monitor HF Space views and interactions
- Adjust content strategy based on engagement

### Quarterly Maintenance

**1. Repository Cleanup**

```bash
# Clean up test files
rm -f test-coordination-debug.txt
rm -f /tmp/framework-hook-*

# Archive old session handoffs
mkdir -p docs/archive/session-handoffs/$(date +%Y-Q%q)
mv .claude/session-archive/SESSION_*.md docs/archive/session-handoffs/$(date +%Y-Q%q)/
```

**2. Documentation Updates**

- Review this maintenance guide
- Update statistics and metrics
- Document new features and changes
- Update troubleshooting sections

**3. Security Review**

- Rotate HF access token if needed
- Review social media account security
- Check for any exposed credentials
- Update authentication documentation

### Troubleshooting

**Reddit Posts Removed:**
```bash
# Symptom: Post doesn't appear in r/AI_Agents
# Cause: Spam filter triggered
# Solution:
# 1. Check account karma (need 10+ comment karma)
# 2. Wait 24-48 hours between link posts
# 3. Message r/AI_Agents mods politely
# 4. Build reputation through comments first
```

**HF Space Not Updating:**
```bash
# Symptom: Data pushed but Space shows old data
# Cause: HF rebuild failed or cached
# Solution:
cd ~/audit-log-viewer
git log -1  # Verify commit pushed
# Check HF Space logs: https://huggingface.co/spaces/tractatus-framework/audit-log-viewer/logs
# Wait 5 minutes for rebuild
# Force refresh browser cache (Ctrl+Shift+R)
```

**Coordination Tracking Stopped:**
```bash
# Symptom: New audit logs show services_involved: []
# Cause: Hook configuration changed or services not logging
# Solution:
# 1. Verify hook is running:
cat .claude/settings.local.json | grep -A 5 "framework-audit-hook"

# 2. Test hook manually:
echo '{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.txt"}}' | .claude/hooks/framework-audit-hook.js

# 3. Check database for recent coordinated decisions:
mongosh tractatus_dev --eval 'db.auditLogs.find({"metadata.services_involved": {$ne: []}}).sort({timestamp: -1}).limit(1)'

# 4. If empty, re-apply coordination tracking implementation
```

**Facebook Link Unavailable:**
```bash
# Symptom: Facebook shows "Link unavailable" for agenticgovernance.digital
# Cause: Open Graph tags not detected or site not crawlable
# Solution:
# 1. Test with Facebook Sharing Debugger:
#    https://developers.facebook.com/tools/debug/?q=https://agenticgovernance.digital
# 2. Verify Open Graph tags in HTML:
curl -s https://agenticgovernance.digital | grep "og:"
# 3. Request Facebook to re-scrape:
#    Use "Scrape Again" button in debugger
```

### Future Enhancements

**Planned Features:**

1. **Automated HF Space Updates:**
   - Cron job to export and push data daily
   - Script: `scripts/auto-update-hf-space.sh`

2. **Reddit Bot Integration:**
   - Automated monitoring of relevant discussions
   - Weekly digest of governance-related posts

3. **Enhanced Coordination Metrics:**
   - Per-service coordination analysis
   - Temporal trends in coordination patterns
   - Anomaly detection in coordination rates

4. **Social Media Analytics:**
   - Track post performance metrics
   - A/B testing for content types
   - Community sentiment analysis

---

## References

**Internal Documentation:**
- Framework Architecture: `docs/FRAMEWORK-ARCHITECTURE.md`
- Session Management: `docs/SESSION_MANAGEMENT_ARCHITECTURE.md`
- Instruction History: `.claude/instruction-history.json`
- HF Presence Plan: `docs/outreach/HUGGINGFACE-PRESENCE-PLAN.md`

**External Links:**
- Reddit r/AI_Agents: https://www.reddit.com/r/AI_Agents/
- HF Space: https://huggingface.co/spaces/tractatus-framework/audit-log-viewer
- Website: https://agenticgovernance.digital
- GitHub: https://github.com/tractatus-framework
- Substack: https://ridingthetiger.substack.com/chat

**Tools:**
- MongoDB Shell: `mongosh tractatus_dev`
- Export Script: `node scripts/export-hf-audit-data.js`
- Reddit Account: u/tractatus-framework
- HF Token: [Stored securely, not in repos]

---

**Document Version:** 1.0
**Last Reviewed:** 2025-11-01
**Next Review:** 2025-12-01