docs: comprehensive social media and HF Space maintenance guide
Created detailed documentation for future Claude Code instances to maintain:
- Reddit presence (u/tractatus-framework, r/AI_Agents engagement)
- Facebook presence (Agentic Governance NZ page)
- Hugging Face Space (audit-log-viewer deployment)
- Deep Interlock coordination tracking implementation
New files:
- docs/outreach/SOCIAL-MEDIA-AND-HF-MAINTENANCE.md (full guide)
- docs/outreach/QUICK-REFERENCE-SOCIAL-MEDIA.md (quick commands)
- docs/outreach/HUGGINGFACE-PRESENCE-PLAN.md (initial setup plan)
- scripts/export-hf-audit-data.js (HF data export script)
- public/images/tractatus-reddit-avatar*.png (Reddit branding)
Key features documented:
- Weekly HF Space update procedure
- Daily Reddit engagement strategy
- Coordination tracking troubleshooting
- Performance metrics and goals
- Complete troubleshooting guide
All procedures include copy-paste commands for easy maintenance.
🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
TheFlow
parent
93837b8dba
commit
51a9f3ca7f
6 changed files with 1410 additions and 0 deletions
387
docs/outreach/HUGGINGFACE-PRESENCE-PLAN.md
Normal file
387
docs/outreach/HUGGINGFACE-PRESENCE-PLAN.md
Normal file
|
|
@ -0,0 +1,387 @@
|
||||||
|
# Hugging Face Presence Plan - Tractatus Framework
|
||||||
|
|
||||||
|
**Date**: 2025-10-31
|
||||||
|
**Purpose**: Establish Tractatus presence on Hugging Face to reach AI/ML research community
|
||||||
|
**Status**: Planning Phase
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why Hugging Face?
|
||||||
|
|
||||||
|
**Strategic Fit:**
|
||||||
|
- Focus on AI ethics and governance aligns with Tractatus mission
|
||||||
|
- Research-oriented community (our target audience)
|
||||||
|
- Open-source first culture
|
||||||
|
- Models come with documentation about limitations/biases (governance mindset)
|
||||||
|
- Platform for ML practitioners, not just consumers
|
||||||
|
|
||||||
|
**Unique Opportunity:**
|
||||||
|
- Very few governance frameworks have Hugging Face presence
|
||||||
|
- Most content is models/datasets - governance tooling is underrepresented
|
||||||
|
- Community values transparency and ethical AI
|
||||||
|
- Tractatus can fill governance gap in HF ecosystem
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: Account Setup (Week 1)
|
||||||
|
|
||||||
|
### 1.1 Create Personal Account
|
||||||
|
- [ ] Sign up at https://huggingface.co/join
|
||||||
|
- [ ] Verify email
|
||||||
|
- [ ] Complete profile:
|
||||||
|
- Name: [Your name or "Tractatus Team"]
|
||||||
|
- Bio: "AI governance researcher. Building architectural constraints for human agency."
|
||||||
|
- Location: Aotearoa New Zealand
|
||||||
|
- Website: https://agenticgovernance.digital
|
||||||
|
|
||||||
|
### 1.2 Create Organization
|
||||||
|
- [ ] Go to https://huggingface.co/organizations/new
|
||||||
|
- [ ] Organization name options:
|
||||||
|
- **Option A**: `tractatus-framework` (descriptive)
|
||||||
|
- **Option B**: `agentic-governance` (brand alignment)
|
||||||
|
- **Option C**: `tractatus` (simple, if available)
|
||||||
|
- [ ] Organization display name: "Tractatus AI Safety Framework"
|
||||||
|
- [ ] Organization description:
|
||||||
|
```
|
||||||
|
Architectural constraints for human agency in AI systems.
|
||||||
|
Open-source governance framework operating in production.
|
||||||
|
Developed in Aotearoa NZ.
|
||||||
|
```
|
||||||
|
- [ ] Set organization email domain (agenticgovernance.digital)
|
||||||
|
- [ ] Add avatar (use tractatus-reddit-avatar-hd.png)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: Documentation & Repository (Week 1-2)
|
||||||
|
|
||||||
|
### 2.1 Organization README
|
||||||
|
Create: `README.md` for organization landing page
|
||||||
|
|
||||||
|
**Content Structure:**
|
||||||
|
```markdown
|
||||||
|
# Tractatus AI Safety Framework
|
||||||
|
|
||||||
|
Architectural constraints for human agency in AI agent deployments.
|
||||||
|
|
||||||
|
## What is Tractatus?
|
||||||
|
|
||||||
|
Production-tested governance framework enforcing constraints through
|
||||||
|
structure, not training. Five architectural principles from Christopher
|
||||||
|
Alexander's pattern languages applied to AI safety.
|
||||||
|
|
||||||
|
## Why Architectural Governance?
|
||||||
|
|
||||||
|
Behavioral training can be manipulated through prompting. We're testing
|
||||||
|
structural enforcement: PreToolUse hooks that intercept actions before
|
||||||
|
execution, services that coordinate through mutual validation, gradient
|
||||||
|
responses to risk levels.
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- **Website**: https://agenticgovernance.digital
|
||||||
|
- **Documentation**: https://agenticgovernance.digital/docs.html
|
||||||
|
- **Architecture**: https://agenticgovernance.digital/architecture.html
|
||||||
|
- **GitHub**: [link]
|
||||||
|
- **License**: Apache 2.0
|
||||||
|
|
||||||
|
## Demos
|
||||||
|
|
||||||
|
- [Framework Audit Viewer](#) - Interactive audit log explorer
|
||||||
|
- [Governance Metrics Dashboard](#) - Real-time framework statistics
|
||||||
|
- [Boundary Decision Explorer](#) - See how services coordinate
|
||||||
|
|
||||||
|
## Datasets
|
||||||
|
|
||||||
|
- [Audit Decision Corpus](#) - 3500+ anonymized governance decisions
|
||||||
|
- [Framework Evolution Log](#) - How principles emerged from failures
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 Link GitHub Repository
|
||||||
|
- [ ] Add GitHub repo to organization (if repo is public)
|
||||||
|
- [ ] Or create "mirror" documentation repo on HF
|
||||||
|
- [ ] Sync README between GitHub and HF
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3: Spaces - Interactive Demos (Week 2-3)
|
||||||
|
|
||||||
|
### 3.1 Space 1: Audit Log Viewer (Priority 1)
|
||||||
|
**Purpose**: Show framework in action through real audit decisions
|
||||||
|
|
||||||
|
**Tech Stack**: Gradio (Python, easy to deploy)
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Search audit logs by service, date, decision type
|
||||||
|
- Filter by pressure level (NORMAL/ELEVATED/HIGH/CRITICAL)
|
||||||
|
- Show service coordination for multi-service decisions
|
||||||
|
- Visualize decision patterns over time
|
||||||
|
|
||||||
|
**Data**: Anonymized subset of audit logs (remove file paths, specific code)
|
||||||
|
|
||||||
|
**Value**: Makes "3500+ audit decisions" tangible and explorable
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.2 Space 2: Governance Metrics Dashboard (Priority 2)
|
||||||
|
**Purpose**: Real-time framework statistics visualization
|
||||||
|
|
||||||
|
**Tech Stack**: Streamlit or Gradio
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Context pressure distribution over time
|
||||||
|
- Service activation patterns
|
||||||
|
- Boundary enforcement statistics
|
||||||
|
- Framework version evolution timeline
|
||||||
|
- "27027 incident" case study deep-dive
|
||||||
|
|
||||||
|
**Data**: Aggregated metrics from production use
|
||||||
|
|
||||||
|
**Value**: Shows operational reality, not theoretical concepts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3.3 Space 3: Boundary Decision Simulator (Priority 3)
|
||||||
|
**Purpose**: Interactive demonstration of how services coordinate
|
||||||
|
|
||||||
|
**Tech Stack**: Gradio with flow diagram visualization
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Input: Simulated AI action (e.g., "Edit values.html")
|
||||||
|
- Output: Step-by-step service coordination
|
||||||
|
- Visual flow: BoundaryEnforcer → CrossReference → ContextPressure → Decision
|
||||||
|
- Show how different pressure levels change outcomes
|
||||||
|
|
||||||
|
**Value**: Educational - helps people understand Deep Interlock principle
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4: Datasets (Week 3-4)
|
||||||
|
|
||||||
|
### 4.1 Audit Decision Corpus
|
||||||
|
**Dataset**: Anonymized audit logs from production use
|
||||||
|
|
||||||
|
**Format**: JSON Lines (.jsonl)
|
||||||
|
|
||||||
|
**Content:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"timestamp": "2025-10-31T10:00:00Z",
|
||||||
|
"service": "BoundaryEnforcer",
|
||||||
|
"decision": "ask",
|
||||||
|
"boundary": "12.2 Innovation",
|
||||||
|
"context_pressure": "NORMAL",
|
||||||
|
"coordination": ["CrossReferenceValidator", "ContextPressureMonitor"],
|
||||||
|
"outcome": "human_approval_required"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Size**: 3500+ decisions (current corpus)
|
||||||
|
|
||||||
|
**Purpose**:
|
||||||
|
- Research dataset for governance pattern analysis
|
||||||
|
- Training data for governance service development
|
||||||
|
- Evidence of production deployment
|
||||||
|
|
||||||
|
**License**: CC BY-SA 4.0 (attribution + share-alike)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4.2 Framework Evolution Log
|
||||||
|
**Dataset**: How architectural principles emerged from failures
|
||||||
|
|
||||||
|
**Format**: Markdown + structured timeline
|
||||||
|
|
||||||
|
**Content**:
|
||||||
|
- Incident reports (e.g., 27027 incident)
|
||||||
|
- Service additions and rationale
|
||||||
|
- Framework version changes
|
||||||
|
- Living Process principle in action
|
||||||
|
|
||||||
|
**Purpose**: Show evidence-based evolution (inst_093)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 5: Model Cards / Documentation (Week 4)
|
||||||
|
|
||||||
|
### 5.1 Framework "Model Card"
|
||||||
|
Even though Tractatus isn't a model, HF supports documentation pages
|
||||||
|
|
||||||
|
**Create**: `model-card.md` explaining:
|
||||||
|
- What problem it solves
|
||||||
|
- How it works architecturally
|
||||||
|
- Limitations and known issues
|
||||||
|
- Intended use cases
|
||||||
|
- Evaluation metrics (audit log analysis)
|
||||||
|
- Ethical considerations (human agency preservation)
|
||||||
|
|
||||||
|
### 5.2 Blog Posts
|
||||||
|
Hugging Face allows blog posts for organizations
|
||||||
|
|
||||||
|
**Topics:**
|
||||||
|
- "Architectural Constraints vs Behavioral Training for AI Governance"
|
||||||
|
- "The 27027 Incident: How Production Failures Drive Framework Evolution"
|
||||||
|
- "Five Architectural Principles from Christopher Alexander Applied to AI Safety"
|
||||||
|
- "3500 Governance Decisions: What We Learned"
|
||||||
|
|
||||||
|
**Frequency**: 1 per month
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 6: Community Engagement (Ongoing)
|
||||||
|
|
||||||
|
### 6.1 Participate in HF Discussions
|
||||||
|
- Comment on AI ethics/governance discussions
|
||||||
|
- Share audit log insights
|
||||||
|
- Respond to questions about governance approaches
|
||||||
|
|
||||||
|
### 6.2 Collaborate with Other Projects
|
||||||
|
- Projects working on AI safety
|
||||||
|
- Governance framework developers
|
||||||
|
- Ethical AI initiatives
|
||||||
|
- Open-source AI tooling
|
||||||
|
|
||||||
|
### 6.3 Update Datasets Quarterly
|
||||||
|
- Add new audit decisions
|
||||||
|
- Document framework evolution
|
||||||
|
- Show Living Process in action
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical Requirements
|
||||||
|
|
||||||
|
### Development Environment
|
||||||
|
- Python 3.9+ (for Gradio/Streamlit Spaces)
|
||||||
|
- Gradio or Streamlit library
|
||||||
|
- MongoDB access (to export audit logs)
|
||||||
|
- Data anonymization scripts
|
||||||
|
|
||||||
|
### Data Preparation
|
||||||
|
1. **Audit Log Anonymization**
|
||||||
|
- Remove file paths
|
||||||
|
- Remove specific code snippets
|
||||||
|
- Keep: service names, decisions, timestamps, coordination patterns
|
||||||
|
- Script: `scripts/export-anonymized-audits.js`
|
||||||
|
|
||||||
|
2. **Metrics Aggregation**
|
||||||
|
- Context pressure distribution
|
||||||
|
- Service activation counts
|
||||||
|
- Boundary enforcement statistics
|
||||||
|
- Script: `scripts/export-metrics.js`
|
||||||
|
|
||||||
|
### Space Deployment
|
||||||
|
- Create requirements.txt for Python dependencies
|
||||||
|
- Write app.py for Gradio/Streamlit interface
|
||||||
|
- Test locally before deploying
|
||||||
|
- Deploy to HF Spaces via git push
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Success Metrics
|
||||||
|
|
||||||
|
### Phase 1 (Setup) - Week 1
|
||||||
|
- [ ] Organization created
|
||||||
|
- [ ] Profile complete with branding
|
||||||
|
- [ ] README published
|
||||||
|
|
||||||
|
### Phase 2 (Content) - Week 2
|
||||||
|
- [ ] At least 1 Space deployed (Audit Log Viewer)
|
||||||
|
- [ ] 1 dataset published (Audit Decision Corpus)
|
||||||
|
- [ ] GitHub repo linked
|
||||||
|
|
||||||
|
### Phase 3 (Engagement) - Month 1-3
|
||||||
|
- [ ] 100+ Space views
|
||||||
|
- [ ] 50+ dataset downloads
|
||||||
|
- [ ] 5+ community discussions participated in
|
||||||
|
- [ ] 1 blog post published
|
||||||
|
|
||||||
|
### Phase 4 (Impact) - Month 3-6
|
||||||
|
- [ ] Other projects referencing Tractatus dataset
|
||||||
|
- [ ] Citations in research papers
|
||||||
|
- [ ] Community contributions (issues, questions, collaborations)
|
||||||
|
- [ ] Cross-promotion with similar governance projects
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resources Needed
|
||||||
|
|
||||||
|
### Time Investment
|
||||||
|
- **Setup (Week 1)**: 4-6 hours
|
||||||
|
- Account creation, organization setup, branding
|
||||||
|
- **Space Development (Week 2-3)**: 12-16 hours
|
||||||
|
- Build Audit Log Viewer in Gradio
|
||||||
|
- Test and deploy
|
||||||
|
- **Dataset Preparation (Week 3-4)**: 8-10 hours
|
||||||
|
- Anonymization scripts
|
||||||
|
- Data export and formatting
|
||||||
|
- Documentation
|
||||||
|
- **Ongoing (Monthly)**: 4-6 hours
|
||||||
|
- Dataset updates
|
||||||
|
- Blog posts
|
||||||
|
- Community engagement
|
||||||
|
|
||||||
|
### Skills Required
|
||||||
|
- Python (Gradio/Streamlit) - for Spaces
|
||||||
|
- Data anonymization - for datasets
|
||||||
|
- Technical writing - for documentation
|
||||||
|
- Community engagement - for discussions
|
||||||
|
|
||||||
|
### Content Preparation
|
||||||
|
- [ ] Anonymize audit logs
|
||||||
|
- [ ] Export metrics aggregations
|
||||||
|
- [ ] Prepare incident case studies
|
||||||
|
- [ ] Write framework documentation
|
||||||
|
- [ ] Create visualization diagrams
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Risks & Mitigation
|
||||||
|
|
||||||
|
### Risk 1: Low Engagement
|
||||||
|
**Mitigation**:
|
||||||
|
- Cross-promote from website/Reddit/Facebook
|
||||||
|
- Collaborate with existing HF governance projects
|
||||||
|
- Regular updates (quarterly dataset releases)
|
||||||
|
|
||||||
|
### Risk 2: Data Privacy Concerns
|
||||||
|
**Mitigation**:
|
||||||
|
- Thorough anonymization
|
||||||
|
- No customer/user data
|
||||||
|
- Only framework decisions (internal operations)
|
||||||
|
- Clear documentation of what's included/excluded
|
||||||
|
|
||||||
|
### Risk 3: Maintenance Burden
|
||||||
|
**Mitigation**:
|
||||||
|
- Start with 1 Space (Audit Log Viewer)
|
||||||
|
- Automate data exports
|
||||||
|
- Quarterly updates, not daily
|
||||||
|
- Community contributions welcome
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps (Immediate)
|
||||||
|
|
||||||
|
1. **Create personal HF account** (5 min)
|
||||||
|
2. **Decide organization name** (tractatus-framework vs agentic-governance)
|
||||||
|
3. **Create anonymization script** for audit logs
|
||||||
|
4. **Build minimum viable Audit Log Viewer** Space
|
||||||
|
5. **Export first dataset** (500-1000 anonymized decisions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Long-Term Vision
|
||||||
|
|
||||||
|
**Year 1**: Establish presence, publish datasets, deploy 2-3 Spaces
|
||||||
|
**Year 2**: Regular blog posts, community collaborations, dataset citations
|
||||||
|
**Year 3**: Reference implementation for governance frameworks on HF
|
||||||
|
|
||||||
|
**Goal**: Make Tractatus the go-to governance framework example on Hugging Face, showing how architectural constraints can work in production.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Alignment with Tractatus Values:**
|
||||||
|
- **Transparency** (inst_010): Public audit logs, open datasets
|
||||||
|
- **Community** (inst_012): Open collaboration, knowledge sharing
|
||||||
|
- **Evidence-Based** (inst_086): Real operational data, not theory
|
||||||
|
- **Candid About Limitations** (inst_088): Honest about what works/doesn't
|
||||||
|
|
||||||
|
**Status**: Ready to proceed with Phase 1
|
||||||
171
docs/outreach/QUICK-REFERENCE-SOCIAL-MEDIA.md
Normal file
171
docs/outreach/QUICK-REFERENCE-SOCIAL-MEDIA.md
Normal file
|
|
@ -0,0 +1,171 @@
|
||||||
|
# Social Media & HF Space - Quick Reference
|
||||||
|
|
||||||
|
**Quick commands for common maintenance tasks**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Update Hugging Face Space (Weekly)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Export fresh audit data
|
||||||
|
cd /home/theflow/projects/tractatus
|
||||||
|
node scripts/export-hf-audit-data.js
|
||||||
|
|
||||||
|
# 2. Check statistics
|
||||||
|
python3 -c "
|
||||||
|
import json
|
||||||
|
with open('./audit-decisions.json') as f:
|
||||||
|
data = json.load(f)
|
||||||
|
coordinated = sum(1 for d in data if len(d.get('coordination', [])) > 0)
|
||||||
|
print(f'Total: {len(data)}, Coordinated: {coordinated}, Rate: {coordinated/len(data)*100:.1f}%')
|
||||||
|
"
|
||||||
|
|
||||||
|
# 3. Deploy to HF Space
|
||||||
|
cp ./audit-decisions.json ~/audit-log-viewer/
|
||||||
|
cd ~/audit-log-viewer
|
||||||
|
git add audit-decisions.json
|
||||||
|
git commit -m "chore: weekly audit data update ($(date +%Y-%m-%d))"
|
||||||
|
git push
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📱 Reddit - Daily Engagement
|
||||||
|
|
||||||
|
**Target:** Comment on 1-2 posts per day in r/AI_Agents
|
||||||
|
|
||||||
|
**Look for:**
|
||||||
|
- Questions about AI governance
|
||||||
|
- Agent architecture discussions
|
||||||
|
- Production deployment challenges
|
||||||
|
|
||||||
|
**Comment Template:**
|
||||||
|
```
|
||||||
|
[Helpful answer to their question]
|
||||||
|
|
||||||
|
[If relevant: The Tractatus Framework handles this through [specific feature].
|
||||||
|
Documentation: https://agenticgovernance.digital/architecture.html#[section]]
|
||||||
|
|
||||||
|
[Optional: Would be interested in your thoughts on [related topic].]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📘 Facebook - Weekly Posts
|
||||||
|
|
||||||
|
**Post Schedule:** Every Monday
|
||||||
|
|
||||||
|
**Template:**
|
||||||
|
```
|
||||||
|
🤖 Tractatus Framework Update - [Date]
|
||||||
|
|
||||||
|
[1-2 paragraph summary of recent work]
|
||||||
|
|
||||||
|
Key improvements:
|
||||||
|
• [Feature 1]
|
||||||
|
• [Feature 2]
|
||||||
|
• [Feature 3]
|
||||||
|
|
||||||
|
🔗 Learn more: https://agenticgovernance.digital
|
||||||
|
📊 Live dashboard: https://huggingface.co/spaces/tractatus-framework/audit-log-viewer
|
||||||
|
|
||||||
|
#AIGovernance #AgenticSystems #OpenSource
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Check Coordination Tracking
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Quick check - last 5 decisions
|
||||||
|
mongosh tractatus_dev --eval '
|
||||||
|
db.auditLogs.find(
|
||||||
|
{},
|
||||||
|
{_id:0, timestamp:1, service:1, "metadata.services_involved":1}
|
||||||
|
).sort({timestamp: -1}).limit(5)
|
||||||
|
'
|
||||||
|
|
||||||
|
# Coordination rate - today
|
||||||
|
mongosh tractatus_dev --eval '
|
||||||
|
var today = new Date();
|
||||||
|
today.setHours(0,0,0,0);
|
||||||
|
var total = db.auditLogs.countDocuments({timestamp: {$gte: today}});
|
||||||
|
var coordinated = db.auditLogs.countDocuments({
|
||||||
|
timestamp: {$gte: today},
|
||||||
|
"metadata.services_involved.1": {$exists: true}
|
||||||
|
});
|
||||||
|
print("Today: " + coordinated + "/" + total + " = " + (coordinated/total*100).toFixed(1) + "%");
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🐛 Troubleshooting
|
||||||
|
|
||||||
|
**Reddit post removed?**
|
||||||
|
```bash
|
||||||
|
# Build karma first - comment on 3-5 posts
|
||||||
|
# Wait 24-48 hours between link posts
|
||||||
|
# Message r/AI_Agents mods if persistent
|
||||||
|
```
|
||||||
|
|
||||||
|
**HF Space not updating?**
|
||||||
|
```bash
|
||||||
|
# Check if commit pushed
|
||||||
|
cd ~/audit-log-viewer && git log -1
|
||||||
|
|
||||||
|
# View HF build logs
|
||||||
|
open https://huggingface.co/spaces/tractatus-framework/audit-log-viewer/logs
|
||||||
|
|
||||||
|
# Force browser cache refresh: Ctrl+Shift+R
|
||||||
|
```
|
||||||
|
|
||||||
|
**Coordination tracking stopped?**
|
||||||
|
```bash
|
||||||
|
# Verify hook configured
|
||||||
|
cat .claude/settings.local.json | grep -A 3 "framework-audit-hook"
|
||||||
|
|
||||||
|
# Test hook manually
|
||||||
|
echo '{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.txt"}}' | \
|
||||||
|
.claude/hooks/framework-audit-hook.js
|
||||||
|
|
||||||
|
# Check for recent coordinated decisions
|
||||||
|
mongosh tractatus_dev --eval '
|
||||||
|
db.auditLogs.findOne(
|
||||||
|
{"metadata.services_involved": {$ne: []}},
|
||||||
|
{timestamp:1, "metadata.services_involved":1}
|
||||||
|
)
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Performance Metrics
|
||||||
|
|
||||||
|
**Check Reddit engagement:**
|
||||||
|
- Account: https://reddit.com/u/tractatus-framework
|
||||||
|
- Target: 10+ comment karma before major posts
|
||||||
|
- Goal: 1 helpful comment per day
|
||||||
|
|
||||||
|
**Check HF Space views:**
|
||||||
|
- Dashboard: https://huggingface.co/spaces/tractatus-framework/audit-log-viewer
|
||||||
|
- Goal: Consistent weekly updates
|
||||||
|
|
||||||
|
**Check coordination rate:**
|
||||||
|
- Current: 1.7% (66/3942 decisions)
|
||||||
|
- Target: 10-20% (as usage grows)
|
||||||
|
- Trend: Monitor monthly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Quick Contacts
|
||||||
|
|
||||||
|
- **HF Token:** [Secure - not in repos]
|
||||||
|
- **Reddit:** u/tractatus-framework
|
||||||
|
- **Facebook:** Agentic Governance NZ
|
||||||
|
- **Substack:** ridingthetiger.substack.com/chat
|
||||||
|
- **GitHub:** github.com/tractatus-framework
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Full Documentation:** `docs/outreach/SOCIAL-MEDIA-AND-HF-MAINTENANCE.md`
|
||||||
667
docs/outreach/SOCIAL-MEDIA-AND-HF-MAINTENANCE.md
Normal file
667
docs/outreach/SOCIAL-MEDIA-AND-HF-MAINTENANCE.md
Normal file
|
|
@ -0,0 +1,667 @@
|
||||||
|
# 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
|
||||||
BIN
public/images/tractatus-reddit-avatar-hd.png
Normal file
BIN
public/images/tractatus-reddit-avatar-hd.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 200 KiB |
BIN
public/images/tractatus-reddit-avatar.png
Normal file
BIN
public/images/tractatus-reddit-avatar.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
185
scripts/export-hf-audit-data.js
Executable file
185
scripts/export-hf-audit-data.js
Executable file
|
|
@ -0,0 +1,185 @@
|
||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Export Anonymized Audit Data for Hugging Face Space
|
||||||
|
*
|
||||||
|
* Exports audit decisions from MongoDB in a safe, anonymized format
|
||||||
|
* for the Tractatus Audit Log Viewer on Hugging Face Spaces.
|
||||||
|
*
|
||||||
|
* Usage: node scripts/export-hf-audit-data.js [--limit=1000]
|
||||||
|
*/
|
||||||
|
|
||||||
|
const { MongoClient } = require('mongodb');
|
||||||
|
const fs = require('fs');
|
||||||
|
const path = require('path');
|
||||||
|
|
||||||
|
// MongoDB connection
|
||||||
|
const MONGO_URI = process.env.MONGO_URI || 'mongodb://localhost:27017';
|
||||||
|
const DB_NAME = 'tractatus_dev';
|
||||||
|
|
||||||
|
// Parse command line args
|
||||||
|
const args = process.argv.slice(2);
|
||||||
|
const limitArg = args.find(arg => arg.startsWith('--limit='));
|
||||||
|
const LIMIT = limitArg ? parseInt(limitArg.split('=')[1]) : null;
|
||||||
|
|
||||||
|
async function exportAuditData() {
|
||||||
|
console.log('🔍 Tractatus Audit Data Export for Hugging Face');
|
||||||
|
console.log('================================================\n');
|
||||||
|
|
||||||
|
const client = new MongoClient(MONGO_URI);
|
||||||
|
|
||||||
|
try {
|
||||||
|
await client.connect();
|
||||||
|
console.log('✓ Connected to MongoDB');
|
||||||
|
|
||||||
|
const db = client.db(DB_NAME);
|
||||||
|
const auditCollection = db.collection('auditLogs');
|
||||||
|
|
||||||
|
// Count total decisions
|
||||||
|
const totalCount = await auditCollection.countDocuments();
|
||||||
|
console.log(`✓ Found ${totalCount} total audit logs`);
|
||||||
|
|
||||||
|
if (LIMIT) {
|
||||||
|
console.log(` → Limiting export to ${LIMIT} decisions`);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Build aggregation pipeline
|
||||||
|
const pipeline = [
|
||||||
|
{
|
||||||
|
$project: {
|
||||||
|
_id: 0,
|
||||||
|
timestamp: '$timestamp',
|
||||||
|
action: '$action',
|
||||||
|
service: {
|
||||||
|
$cond: {
|
||||||
|
if: { $eq: ['$action', 'context_pressure_analysis'] },
|
||||||
|
then: 'ContextPressureMonitor',
|
||||||
|
else: {
|
||||||
|
$cond: {
|
||||||
|
if: { $regexMatch: { input: '$action', regex: /boundary/ } },
|
||||||
|
then: 'BoundaryEnforcer',
|
||||||
|
else: '$action'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
decision: {
|
||||||
|
$cond: {
|
||||||
|
if: '$allowed',
|
||||||
|
then: 'allow',
|
||||||
|
else: 'deny'
|
||||||
|
}
|
||||||
|
},
|
||||||
|
boundary: '$boundary',
|
||||||
|
boundary_domain: '$domain',
|
||||||
|
context_pressure: '$metadata.pressure_level',
|
||||||
|
metadata: '$metadata',
|
||||||
|
// Exclude sensitive data
|
||||||
|
// No file paths, no specific code, no user info
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{ $sort: { timestamp: -1 } }
|
||||||
|
];
|
||||||
|
|
||||||
|
if (LIMIT) {
|
||||||
|
pipeline.push({ $limit: LIMIT });
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log('\n📊 Exporting audit decisions...');
|
||||||
|
|
||||||
|
const decisions = await auditCollection.aggregate(pipeline).toArray();
|
||||||
|
|
||||||
|
console.log(`✓ Exported ${decisions.length} decisions`);
|
||||||
|
|
||||||
|
// Anonymize and clean data
|
||||||
|
const anonymized = decisions.map(d => {
|
||||||
|
// Clean boundary format
|
||||||
|
let boundary = d.boundary || 'N/A';
|
||||||
|
if (boundary && typeof boundary === 'string' && boundary.includes(':')) {
|
||||||
|
// Format: "12.2: Innovation cannot be proceduralized"
|
||||||
|
const parts = boundary.split(':');
|
||||||
|
boundary = `${parts[0].trim()}: ${parts[1]?.trim() || ''}`.substring(0, 100);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Extract service name from action
|
||||||
|
let service = d.service || 'Unknown';
|
||||||
|
|
||||||
|
// Determine if there was service coordination (check metadata)
|
||||||
|
let coordination = [];
|
||||||
|
if (d.metadata && d.metadata.services_involved) {
|
||||||
|
coordination = d.metadata.services_involved;
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
timestamp: d.timestamp,
|
||||||
|
action: d.action,
|
||||||
|
service: service,
|
||||||
|
decision: d.decision || 'unknown',
|
||||||
|
boundary: boundary,
|
||||||
|
boundary_domain: d.boundary_domain || null,
|
||||||
|
context_pressure: d.context_pressure || 'NORMAL',
|
||||||
|
coordination: coordination
|
||||||
|
};
|
||||||
|
});
|
||||||
|
|
||||||
|
// Statistics
|
||||||
|
console.log('\n📈 Export Statistics:');
|
||||||
|
console.log(` Total decisions: ${anonymized.length}`);
|
||||||
|
|
||||||
|
const serviceCount = {};
|
||||||
|
const decisionCount = {};
|
||||||
|
const pressureCount = {};
|
||||||
|
|
||||||
|
anonymized.forEach(d => {
|
||||||
|
serviceCount[d.service] = (serviceCount[d.service] || 0) + 1;
|
||||||
|
decisionCount[d.decision] = (decisionCount[d.decision] || 0) + 1;
|
||||||
|
pressureCount[d.context_pressure] = (pressureCount[d.context_pressure] || 0) + 1;
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log('\n By Service:');
|
||||||
|
Object.entries(serviceCount).sort((a, b) => b[1] - a[1]).forEach(([service, count]) => {
|
||||||
|
console.log(` ${service}: ${count}`);
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log('\n By Decision:');
|
||||||
|
Object.entries(decisionCount).forEach(([decision, count]) => {
|
||||||
|
console.log(` ${decision}: ${count}`);
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log('\n By Pressure Level:');
|
||||||
|
Object.entries(pressureCount).forEach(([pressure, count]) => {
|
||||||
|
console.log(` ${pressure}: ${count}`);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Write to JSON file
|
||||||
|
const outputPath = path.join(__dirname, '..', 'hf-spaces', 'audit-log-viewer', 'audit-decisions.json');
|
||||||
|
|
||||||
|
// Ensure directory exists
|
||||||
|
const outputDir = path.dirname(outputPath);
|
||||||
|
if (!fs.existsSync(outputDir)) {
|
||||||
|
fs.mkdirSync(outputDir, { recursive: true });
|
||||||
|
console.log(`\n✓ Created output directory: ${outputDir}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
fs.writeFileSync(outputPath, JSON.stringify(anonymized, null, 2));
|
||||||
|
|
||||||
|
const fileSize = (fs.statSync(outputPath).size / 1024 / 1024).toFixed(2);
|
||||||
|
console.log(`\n✓ Exported to: ${outputPath}`);
|
||||||
|
console.log(` File size: ${fileSize} MB`);
|
||||||
|
|
||||||
|
console.log('\n✅ Export complete!');
|
||||||
|
console.log('\nNext steps:');
|
||||||
|
console.log(' 1. Review audit-decisions.json for any sensitive data');
|
||||||
|
console.log(' 2. Copy to HF Space repository');
|
||||||
|
console.log(' 3. Deploy Gradio app');
|
||||||
|
|
||||||
|
} catch (error) {
|
||||||
|
console.error('❌ Export failed:', error);
|
||||||
|
process.exit(1);
|
||||||
|
} finally {
|
||||||
|
await client.close();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Run export
|
||||||
|
exportAuditData();
|
||||||
Loading…
Add table
Reference in a new issue