diff --git a/docs/PHASE-2-COST-ESTIMATES.md b/docs/PHASE-2-COST-ESTIMATES.md new file mode 100644 index 00000000..cc79456e --- /dev/null +++ b/docs/PHASE-2-COST-ESTIMATES.md @@ -0,0 +1,510 @@ +# Phase 2 Cost Estimates: Hosting + API Usage + +**Project**: Tractatus AI Safety Framework Website +**Phase**: 2 of 3 +**Created**: 2025-10-07 +**Currency**: USD (approximate NZD conversion: ×1.65) +**Planning Horizon**: 3 months (Phase 2 duration) + +--- + +## Table of Contents + +1. [Executive Summary](#executive-summary) +2. [One-Time Costs](#one-time-costs) +3. [Monthly Recurring Costs](#monthly-recurring-costs) +4. [OVHCloud Hosting Options](#ovhcloud-hosting-options) +5. [Claude API Pricing](#claude-api-pricing) +6. [Usage Scenarios](#usage-scenarios) +7. [Cost Optimization Strategies](#cost-optimization-strategies) +8. [Budget Recommendations](#budget-recommendations) + +--- + +## Executive Summary + +### Total Phase 2 Costs (3 months) + +| Scenario | One-Time | Monthly | 3-Month Total | Notes | +|----------|----------|---------|---------------|-------| +| **Minimal** | $50 | $80 | $290 | Basic VPS, light API usage | +| **Standard** | $100 | $150 | $550 | Recommended for soft launch | +| **High Usage** | $200 | $300 | $1,100 | Heavy AI features, peak traffic | + +**Recommended Budget**: **$550 USD** (~$900 NZD) for 3-month Phase 2 + +**Ongoing Monthly** (post-launch): $150-200 USD (~$250-330 NZD) + +--- + +## One-Time Costs + +### Initial Setup (First Month Only) + +| Item | Cost (USD) | Notes | +|------|------------|-------| +| **Domain Registration** | $15-30/year | `mysy.digital` (if not already owned) | +| **SSL Certificate** | $0 | Let's Encrypt (free) | +| **Development Tools** | $0 | Open source (Git, Node.js, MongoDB) | +| **Migration Services** | $0 | Self-managed deployment | +| **Security Audit Tools** | $0-50 | Free tier (npm audit, Trivy) or paid scans | +| **Load Testing Tools** | $0-50 | k6 (free), Artillery (free tier) | +| **Email Setup** | $0 | ProtonMail existing account | +| **Analytics Setup** | $0 | Self-hosted Plausible/Matomo | +| **Backup Storage** | $0-20 | Initial backup storage (if off-server) | +| **Contingency** | $50 | Unexpected setup costs | + +**Total One-Time**: **$50-200 USD** + +--- + +## Monthly Recurring Costs + +### Breakdown by Service + +#### 1. Hosting (OVHCloud VPS) + +| Tier | Specs | Price/Month | Use Case | +|------|-------|-------------|----------| +| **VPS Starter** | 1 vCore, 2GB RAM, 20GB SSD | $7-10 | Development/testing only | +| **VPS Value** | 1 vCore, 2GB RAM, 40GB SSD | $10-15 | Light traffic (<1000 visitors/month) | +| **VPS Essential** | 2 vCore, 4GB RAM, 80GB SSD | $20-30 | **Recommended for soft launch** | +| **VPS Comfort** | 2 vCore, 8GB RAM, 160GB SSD | $40-50 | Moderate traffic (1000-5000 visitors/month) | +| **VPS Elite** | 4 vCore, 16GB RAM, 320GB SSD | $80-100 | High traffic (5000+ visitors/month) | + +**Recommendation**: Start with **VPS Essential ($20-30)**, upgrade if needed. + +#### 2. Claude API (Anthropic) + +**Pricing Model** (as of 2025): +- **Claude Sonnet 4.5**: + - Input: $3.00 per million tokens + - Output: $15.00 per million tokens + - Context: 200K tokens + +**Estimated Usage**: + +| Feature | Requests/Month | Tokens/Request (avg) | Monthly Cost | +|---------|----------------|----------------------|--------------| +| **Blog Topic Suggestions** | 100 | 5K input + 1K output | $2.00 | +| **Blog Outline Generation** | 30 | 10K input + 5K output | $3.00 | +| **Media Inquiry Triage** | 50 | 3K input + 500 output | $0.75 | +| **Case Study Analysis** | 20 | 15K input + 3K output | $2.00 | +| **Moderation Assistance** | 50 | 5K input + 1K output | $1.50 | +| **Miscellaneous** | 50 | 5K input + 1K output | $1.50 | + +**Total API Cost (Light Usage)**: **$10-15/month** +**Total API Cost (Standard)**: **$30-50/month** +**Total API Cost (Heavy)**: **$100-200/month** + +#### 3. Additional Services + +| Service | Cost/Month | Notes | +|---------|------------|-------| +| **Bandwidth** | $0-5 | Usually included in VPS, overage rare | +| **Backups (Off-site)** | $0-10 | OVHCloud Snapshot or Backblaze B2 | +| **Domain Renewal** | $1-3 | Amortized annual cost | +| **Email (ProtonMail)** | $0 | Existing account (free tier) | +| **Analytics (Self-hosted)** | $0 | Plausible/Matomo on same VPS | +| **Error Tracking** | $0-10 | Sentry free tier (5K events/month) or self-hosted | +| **Uptime Monitoring** | $0-5 | UptimeRobot free tier or self-hosted | +| **CDN (Optional)** | $0-20 | Cloudflare Free tier or paid | + +**Total Additional**: **$0-50/month** + +--- + +## OVHCloud Hosting Options + +### Recommended Configuration: VPS Essential + +**Specs**: +- 2 vCores (Intel Xeon or AMD EPYC) +- 4GB RAM +- 80GB SSD NVMe +- 500 Mbps bandwidth (unlimited traffic) +- 1 IPv4 + 1 IPv6 +- Anti-DDoS protection included + +**Price**: **$20-30/month** (varies by region) + +**Justification**: +- Handles MongoDB (2GB RAM minimum recommended) +- Supports Node.js application + Nginx +- Room for Plausible Analytics +- Suitable for 1,000-5,000 visitors/month +- Upgrade path available (scale vertically) + +### Alternative: Hetzner Cloud (European Hosting) + +If OVHCloud is unavailable or too expensive: + +**Hetzner CX21**: +- 2 vCPU +- 4GB RAM +- 40GB SSD +- 20TB traffic +- **€4.90/month (~$5.30 USD)** + +**Hetzner CX31**: +- 2 vCPU +- 8GB RAM +- 80GB SSD +- 20TB traffic +- **€8.90/month (~$9.65 USD)** + +**Note**: Hetzner has excellent pricing but may have fewer NZ/Oceania users. OVHCloud has better global presence. + +--- + +## Claude API Pricing + +### Pricing Tiers (Anthropic - 2025) + +| Model | Input (per 1M tokens) | Output (per 1M tokens) | Context Window | +|-------|----------------------|------------------------|----------------| +| **Claude Haiku 4.0** | $0.25 | $1.25 | 200K | +| **Claude Sonnet 4.5** | $3.00 | $15.00 | 200K | +| **Claude Opus 4.0** | $15.00 | $75.00 | 200K | + +**Recommendation**: **Claude Sonnet 4.5** (best balance of quality and cost) + +### Token Usage Estimation + +**Average Request Breakdown**: + +1. **Blog Topic Suggestion**: + - Input: 3K tokens (recent news summaries) + - Output: 500 tokens (5-10 topic suggestions) + - Cost per request: $0.02 + +2. **Blog Outline Generation**: + - Input: 8K tokens (topic + guidelines + examples) + - Output: 3K tokens (detailed outline) + - Cost per request: $0.07 + +3. **Media Inquiry Triage**: + - Input: 2K tokens (inquiry text + classification criteria) + - Output: 300 tokens (classification + priority + draft response) + - Cost per request: $0.01 + +4. **Case Study Analysis**: + - Input: 10K tokens (submission + Tractatus framework docs) + - Output: 2K tokens (relevance analysis + categorization) + - Cost per request: $0.06 + +### Monthly Usage Scenarios + +#### Scenario 1: Light Usage (Soft Launch) +- 30 blog topic checks +- 10 blog outlines +- 20 media inquiries +- 10 case study analyses +- **Total**: ~$5-10/month + +#### Scenario 2: Standard Usage (Active Moderation) +- 100 blog topic checks +- 30 blog outlines +- 50 media inquiries +- 20 case study analyses +- **Total**: ~$30-50/month + +#### Scenario 3: Heavy Usage (Full Production) +- 300 blog topic checks +- 100 blog outlines +- 150 media inquiries +- 50 case study analyses +- **Total**: ~$100-200/month + +--- + +## Usage Scenarios + +### Scenario 1: Minimal (Development/Testing) + +**Use Case**: Low traffic, testing AI features + +| Cost Item | Amount | +|-----------|--------| +| VPS (Value tier) | $15 | +| Claude API (light) | $10 | +| Backups | $5 | +| Domain (amortized) | $2 | +| **Monthly Total** | **$32** | +| **3-Month Total** | **$96** | + +**Limitations**: +- 500-1,000 visitors/month max +- Limited AI usage (testing only) +- Single-server (no redundancy) + +--- + +### Scenario 2: Standard (Recommended for Soft Launch) + +**Use Case**: Soft launch with 20-50 users, moderate AI usage + +| Cost Item | Amount | +|-----------|--------| +| VPS (Essential tier) | $30 | +| Claude API (standard) | $50 | +| Backups | $10 | +| Error tracking | $10 | +| Domain (amortized) | $2 | +| **Monthly Total** | **$102** | +| **3-Month Total** | **$306** | +| **With setup costs** | **$406** | + +**Capabilities**: +- 1,000-5,000 visitors/month +- 30 blog posts/month (AI-assisted) +- 50 media inquiries/month +- 20 case studies/month +- Monitoring and error tracking + +**Recommendation**: **This is the sweet spot for Phase 2** + +--- + +### Scenario 3: High Usage (Peak Production) + +**Use Case**: High traffic, heavy AI features + +| Cost Item | Amount | +|-----------|--------| +| VPS (Comfort tier) | $50 | +| Claude API (heavy) | $200 | +| Backups | $15 | +| Error tracking | $10 | +| CDN | $20 | +| Domain (amortized) | $2 | +| **Monthly Total** | **$297** | +| **3-Month Total** | **$891** | +| **With setup costs** | **$1,091** | + +**Capabilities**: +- 5,000-10,000 visitors/month +- 100+ blog posts/month +- 150+ media inquiries/month +- 50+ case studies/month +- CDN for global performance + +**When to use**: Phase 3 (public launch) or if soft launch exceeds expectations + +--- + +## Cost Optimization Strategies + +### 1. API Cost Reduction + +**Techniques**: +- **Caching**: Cache AI responses for identical queries (30-day TTL) +- **Batch Processing**: Group similar requests (e.g., weekly topic suggestions) +- **Haiku for Simple Tasks**: Use Claude Haiku for media triage (5x cheaper) +- **Rate Limiting**: Cap AI requests per user/day +- **Human Overrides**: Allow admins to skip AI for trivial cases + +**Savings**: 30-50% reduction in API costs + +### 2. Hosting Cost Reduction + +**Techniques**: +- **Start Small**: Begin with VPS Value, upgrade as needed +- **Annual Billing**: OVHCloud offers ~20% discount for annual payment +- **Resource Optimization**: Optimize database queries, enable caching +- **Self-Host Everything**: Analytics, error tracking, monitoring (no SaaS fees) +- **Cloudflare Free Tier**: CDN + DDoS protection at no cost + +**Savings**: 20-30% reduction in hosting costs + +### 3. Bandwidth Optimization + +**Techniques**: +- **Image Optimization**: WebP format, lazy loading +- **Compression**: Gzip/Brotli for all text assets +- **CDN**: Offload static assets to Cloudflare +- **Minimize Dependencies**: No unnecessary JavaScript libraries + +**Savings**: Avoid bandwidth overage fees + +--- + +## Budget Recommendations + +### Phase 2 Budget Allocation + +**Total Recommended Budget**: **$550 USD** (~$900 NZD) + +**Breakdown**: +- **Setup costs**: $100 (one-time) +- **Month 1**: $150 (infrastructure + initial AI usage) +- **Month 2**: $150 (AI features rollout) +- **Month 3**: $150 (soft launch) + +### Contingency Planning + +**Recommended Buffer**: **+20%** ($110 USD / ~$180 NZD) + +**Reasons**: +- Unexpected traffic spikes +- API usage higher than estimated +- Additional tools/services needed +- Domain/email issues + +**Total with Contingency**: **$660 USD** (~$1,090 NZD) + +--- + +## Monthly Budget Template (Post-Launch) + +### Baseline Monthly Costs (Standard Usage) + +``` +Fixed Costs: + VPS Essential (OVHCloud) $30 + Domain (amortized annual) $2 + Backups (off-site) $10 + Error Tracking (Sentry free) $0 + Analytics (self-hosted) $0 + ───────────────────────────────────── + Subtotal Fixed $42 + +Variable Costs: + Claude API (30-50 requests/day) $50 + Bandwidth (if overage) $0 + CDN (Cloudflare Free) $0 + Support/Maintenance $0 + ───────────────────────────────────── + Subtotal Variable $50 + +Total Monthly (Standard) $92 + +Rounded Budget Recommendation: $100/month +``` + +### Annual Cost Projection (Year 1) + +``` +Phase 2 (3 months): $550 +Phase 3 (9 months): $900 (assuming $100/month average) +───────────────────────────── +Year 1 Total: $1,450 USD (~$2,400 NZD) +``` + +--- + +## Cost Comparison: Self-Hosted vs. Cloud Services + +### Option 1: Self-Hosted (Recommended) + +| Service | Provider | Cost | +|---------|----------|------| +| Hosting | OVHCloud VPS | $30/month | +| Analytics | Plausible (self-hosted) | $0 | +| Error Tracking | GlitchTip (self-hosted) | $0 | +| Monitoring | Self-hosted scripts | $0 | +| Backups | OVHCloud Snapshots | $10/month | +| **Total** | | **$40/month** | + +### Option 2: Cloud Services + +| Service | Provider | Cost | +|---------|----------|------| +| Hosting | Vercel/Netlify | $20/month | +| Database | MongoDB Atlas | $25/month | +| Analytics | Plausible (cloud) | $9/month | +| Error Tracking | Sentry (cloud) | $26/month | +| Monitoring | UptimeRobot Pro | $7/month | +| **Total** | | **$87/month** | + +**Savings with Self-Hosted**: **$47/month** ($564/year) + +**Tradeoff**: More setup/maintenance effort, but better privacy and cost control. + +--- + +## Payment Methods & Billing + +### OVHCloud Payment Options +- Credit/Debit Card (Visa, MasterCard) +- PayPal +- Bank Transfer (for annual plans) +- Cryptocurrency (some regions) + +### Anthropic Claude API +- Credit/Debit Card +- Pay-as-you-go (monthly billing) +- Enterprise plans (prepaid credits) + +### Billing Schedule +- **VPS**: Monthly (or annual for discount) +- **Claude API**: Monthly (arrears) +- **Domain**: Annual +- **Backups**: Monthly + +--- + +## Currency Conversion (NZD) + +**Exchange Rate** (as of 2025-10-07): **1 USD = ~1.65 NZD** + +| USD Amount | NZD Equivalent | +|------------|----------------| +| $50 | ~$83 | +| $100 | ~$165 | +| $150 | ~$248 | +| $300 | ~$495 | +| $550 | ~$908 | +| $1,000 | ~$1,650 | + +**Note**: Exchange rates fluctuate. Add 5-10% buffer for volatility. + +--- + +## Approval Checklist + +Before proceeding with Phase 2, confirm: + +- [ ] **Budget approved**: $550-660 USD (~$900-1,090 NZD) for 3 months +- [ ] **Monthly ongoing**: $100-150 USD (~$165-250 NZD) acceptable +- [ ] **Payment method**: Credit card or PayPal available +- [ ] **OVHCloud account**: Created and verified +- [ ] **Anthropic account**: API access approved +- [ ] **Currency**: USD or NZD budget confirmed +- [ ] **Contingency**: 20% buffer accepted ($110 USD / ~$180 NZD) + +--- + +## Appendix: Cost Calculator + +### Interactive Budget Calculator (Conceptual) + +```javascript +// Example usage: +const monthlyBudget = calculateMonthlyCost({ + vps: 'essential', // $30 + apiRequests: 500, // ~$50 + backups: true, // $10 + cdn: false, // $0 + errorTracking: 'free' // $0 +}); + +console.log(monthlyBudget); // $90 +``` + +**Implementation**: Could be added to admin dashboard for real-time cost tracking. + +--- + +## Revision History + +| Date | Version | Changes | +|------|---------|---------| +| 2025-10-07 | 1.0 | Initial cost estimates for Phase 2 | + +--- + +**Document Owner**: John Stroh +**Last Updated**: 2025-10-07 +**Next Review**: Monthly (during Phase 2) +**Contributors**: Claude Code (Anthropic Sonnet 4.5) diff --git a/docs/PHASE-2-INFRASTRUCTURE-PLAN.md b/docs/PHASE-2-INFRASTRUCTURE-PLAN.md new file mode 100644 index 00000000..4680addc --- /dev/null +++ b/docs/PHASE-2-INFRASTRUCTURE-PLAN.md @@ -0,0 +1,1175 @@ +# Phase 2 Infrastructure Plan + +**Project**: Tractatus AI Safety Framework Website +**Phase**: 2 of 3 +**Created**: 2025-10-07 +**Owner**: John Stroh +**Status**: Planning +**Target Deployment**: TBD (awaiting Phase 2 approval) + +--- + +## Table of Contents + +1. [Architecture Overview](#architecture-overview) +2. [Server Specifications](#server-specifications) +3. [Network Architecture](#network-architecture) +4. [Deployment Procedures](#deployment-procedures) +5. [Security Hardening](#security-hardening) +6. [Monitoring & Alerting](#monitoring--alerting) +7. [Backup & Disaster Recovery](#backup--disaster-recovery) +8. [DNS & Domain Configuration](#dns--domain-configuration) +9. [SSL/TLS Configuration](#ssltls-configuration) +10. [Environment Configuration](#environment-configuration) +11. [Deployment Checklist](#deployment-checklist) + +--- + +## Architecture Overview + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Internet │ +└────────────────────┬────────────────────────────────────────┘ + │ + ┌────────▼────────┐ + │ Cloudflare │ (Optional CDN + DDoS protection) + │ DNS + Proxy │ + └────────┬────────┘ + │ + ┌────────▼────────┐ + │ OVHCloud VPS │ (Ubuntu 22.04 LTS) + │ mysy.digital │ + └────────┬────────┘ + │ + ┌────────────┴────────────┐ + │ │ + ┌────▼─────┐ ┌──────▼──────┐ + │ Nginx │ │ Fail2ban │ + │ :80/443 │ │ Firewall │ + └────┬─────┘ └─────────────┘ + │ + ┌────▼─────┐ + │ Node.js │ + │ Express │ + │ :9000 │ + └────┬─────┘ + │ + ┌────▼─────┐ + │ MongoDB │ + │ :27017 │ + └──────────┘ +``` + +### Component Stack + +| Layer | Component | Version | Purpose | +|-------|-----------|---------|---------| +| **CDN** | Cloudflare | Free tier | DDoS protection, CDN (optional) | +| **DNS** | Cloudflare/OVH | - | Domain nameservers | +| **Firewall** | UFW + Fail2ban | Latest | Perimeter security | +| **Web Server** | Nginx | 1.24+ | Reverse proxy, SSL termination | +| **Application** | Node.js + Express | 18 LTS + 4.x | Tractatus platform | +| **Database** | MongoDB | 7.x | Document storage | +| **Process Manager** | systemd | System default | Service management | +| **SSL/TLS** | Let's Encrypt | Latest | HTTPS certificates | +| **Email** | ProtonBridge | Latest | SMTP gateway | +| **Analytics** | Plausible (self-hosted) | Latest | Privacy-respecting analytics | +| **Monitoring** | Self-hosted scripts | Custom | Uptime, performance | + +--- + +## Server Specifications + +### Recommended Configuration (OVHCloud VPS Essential) + +**Compute**: +- vCores: 2 (Intel Xeon or AMD EPYC) +- RAM: 4GB DDR4 +- Storage: 80GB SSD NVMe +- Architecture: x86_64 + +**Network**: +- Bandwidth: 500 Mbps +- Traffic: Unlimited +- IPv4: 1 dedicated +- IPv6: 1 dedicated (/64 subnet) +- Anti-DDoS: Included + +**Operating System**: +- Distribution: Ubuntu 22.04 LTS (Jammy Jellyfish) +- Kernel: 5.15+ (HWE) +- Init system: systemd + +**Geographic Location**: +- Preferred: Singapore or Australia (closest to NZ) +- Alternative: Europe (if latency acceptable) +- Avoid: US East/West (regulatory, latency) + +**Cost**: ~$20-30/month USD + +--- + +### Server Sizing Rationale + +**Memory Allocation**: +- MongoDB: ~1.5GB (production database + WiredTiger cache) +- Node.js: ~1GB (application + dependencies) +- Nginx: ~100MB (minimal footprint) +- System: ~500MB (OS, utilities) +- Plausible Analytics: ~500MB (if self-hosted) +- Buffer: ~400MB (peak load) +- **Total**: ~4GB (fits VPS Essential) + +**Storage Allocation**: +- OS + System: ~10GB +- MongoDB data: ~20GB (estimated Year 1) +- Application code: ~2GB (node_modules) +- Logs: ~5GB (1-year retention with rotation) +- Backups (on-server): ~20GB (7-day retention) +- Free space: ~23GB (buffer) +- **Total**: ~80GB (VPS Essential) + +**CPU Usage**: +- Typical: <20% (2 vCores) +- Peak: <60% (during deployments, backups) +- Acceptable: 2 vCores sufficient for Phase 2 traffic + +--- + +## Network Architecture + +### Firewall Rules (UFW) + +**Allow**: +```bash +# SSH (restricted to specific IPs in production) +ufw allow from to any port 22 proto tcp comment 'SSH Admin' + +# HTTP (redirect to HTTPS) +ufw allow 80/tcp comment 'HTTP' + +# HTTPS +ufw allow 443/tcp comment 'HTTPS' + +# MongoDB (localhost only, no external access) +ufw allow from 127.0.0.1 to any port 27017 proto tcp comment 'MongoDB local' +``` + +**Deny** (default): +```bash +# Default deny incoming +ufw default deny incoming + +# Default allow outgoing (for apt, npm, git) +ufw default allow outgoing +``` + +**Activate**: +```bash +ufw enable +ufw status verbose +``` + +--- + +### Port Configuration + +| Service | Port | Bind Address | Firewall | Notes | +|---------|------|--------------|----------|-------| +| **SSH** | 22 | 0.0.0.0 | Restricted IP | Key-only auth | +| **HTTP** | 80 | 0.0.0.0 | Allow | Redirect to 443 | +| **HTTPS** | 443 | 0.0.0.0 | Allow | Nginx reverse proxy | +| **Node.js** | 9000 | 127.0.0.1 | Deny | Internal only | +| **MongoDB** | 27017 | 127.0.0.1 | Deny | Internal only | + +--- + +## Deployment Procedures + +### Initial Server Setup + +#### 1. Provision VPS + +**OVHCloud Control Panel**: +1. Select VPS Essential tier +2. Choose Ubuntu 22.04 LTS +3. Select geographic region (Singapore/Australia) +4. Generate root password (save securely) +5. Provision (5-10 minutes) + +**Verify Access**: +```bash +ssh root@ +``` + +--- + +#### 2. Create Non-Root User + +```bash +# Create deploy user +adduser tractatus +usermod -aG sudo tractatus + +# Set up SSH key auth +mkdir -p /home/tractatus/.ssh +chmod 700 /home/tractatus/.ssh +``` + +**On local machine**: +```bash +# Generate SSH key (if not exists) +ssh-keygen -t ed25519 -C "tractatus-deploy" + +# Copy public key to server +ssh-copy-id tractatus@ +``` + +**Test**: +```bash +ssh tractatus@ +``` + +--- + +#### 3. Harden SSH + +```bash +# Edit SSH config +sudo nano /etc/ssh/sshd_config +``` + +**Changes**: +``` +PermitRootLogin no +PasswordAuthentication no +PubkeyAuthentication yes +Port 22 # Consider changing to non-standard port (2222) +AllowUsers tractatus +``` + +**Restart SSH**: +```bash +sudo systemctl restart sshd +``` + +--- + +#### 4. System Updates + +```bash +# Update package lists +sudo apt update + +# Upgrade all packages +sudo apt upgrade -y + +# Install essential tools +sudo apt install -y \ + curl \ + wget \ + git \ + ufw \ + fail2ban \ + htop \ + vim \ + certbot \ + python3-certbot-nginx +``` + +--- + +#### 5. Configure Firewall + +```bash +# Allow SSH (before enabling UFW!) +sudo ufw allow from to any port 22 proto tcp + +# Allow HTTP/HTTPS +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp + +# Enable firewall +sudo ufw enable +sudo ufw status verbose +``` + +--- + +### Install Application Stack + +#### 1. Install Node.js + +```bash +# Add NodeSource repository (Node 18 LTS) +curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - + +# Install Node.js +sudo apt install -y nodejs + +# Verify +node --version # v18.x.x +npm --version # 9.x.x +``` + +--- + +#### 2. Install MongoDB + +```bash +# Import MongoDB public GPG key +curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \ + sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/mongodb-server-7.0.gpg + +# Add MongoDB repository +echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \ + sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list + +# Update and install +sudo apt update +sudo apt install -y mongodb-org + +# Start MongoDB +sudo systemctl start mongod +sudo systemctl enable mongod + +# Verify +sudo systemctl status mongod +mongosh --eval 'db.version()' # 7.0.x +``` + +--- + +#### 3. Install Nginx + +```bash +# Install Nginx +sudo apt install -y nginx + +# Start Nginx +sudo systemctl start nginx +sudo systemctl enable nginx + +# Verify +sudo systemctl status nginx +nginx -v # nginx/1.24.x +``` + +--- + +### Deploy Application + +#### 1. Clone Repository + +```bash +# Create application directory +sudo mkdir -p /var/www/tractatus +sudo chown tractatus:tractatus /var/www/tractatus + +# Clone repository +cd /var/www/tractatus +git clone https://github.com/your-org/tractatus.git . + +# Install dependencies +npm install --production +``` + +--- + +#### 2. Configure Environment + +```bash +# Create production environment file +cp .env.example .env.production + +# Edit configuration +nano .env.production +``` + +**Production Environment Variables**: +```bash +# Application +NODE_ENV=production +PORT=9000 +APP_NAME=Tractatus + +# MongoDB +MONGODB_URI=mongodb://localhost:27017/tractatus_prod +MONGODB_PORT=27017 + +# JWT +JWT_SECRET= +JWT_EXPIRY=7d +JWT_AUDIENCE=tractatus-admin +JWT_ISSUER=tractatus + +# Claude API +CLAUDE_API_KEY= +CLAUDE_MODEL=claude-sonnet-4-5-20250929 +CLAUDE_MAX_TOKENS=200000 + +# Email (ProtonBridge) +SMTP_HOST=127.0.0.1 +SMTP_PORT=1025 +SMTP_USER=contact@mysy.digital +SMTP_PASSWORD= +SMTP_FROM=contact@mysy.digital + +# Admin +ADMIN_EMAIL=john.stroh.nz@pm.me + +# Logging +LOG_LEVEL=info +LOG_FILE=/var/log/tractatus/app.log +``` + +**Generate JWT Secret**: +```bash +node -e "console.log(require('crypto').randomBytes(64).toString('hex'))" +``` + +--- + +#### 3. Database Initialization + +```bash +# Create production database and admin user +mongosh tractatus_prod --eval " + db.createUser({ + user: 'tractatus', + pwd: '', + roles: [{ role: 'readWrite', db: 'tractatus_prod' }] + }) +" + +# Run migration scripts +npm run init:db + +# Seed admin user +npm run seed:admin +``` + +--- + +#### 4. Build Assets + +```bash +# Build Tailwind CSS for production +npm run build:css + +# Verify build +ls -lh public/css/tailwind.css # Should be ~24KB minified +``` + +--- + +#### 5. Create Systemd Service + +```bash +# Create service file +sudo nano /etc/systemd/system/tractatus.service +``` + +**Service Configuration**: +```ini +[Unit] +Description=Tractatus AI Safety Framework +Documentation=https://mysy.digital/docs +After=network.target mongod.service + +[Service] +Type=simple +User=tractatus +WorkingDirectory=/var/www/tractatus +Environment=NODE_ENV=production +EnvironmentFile=/var/www/tractatus/.env.production +ExecStart=/usr/bin/node src/server.js +Restart=on-failure +RestartSec=10 +StandardOutput=journal +StandardError=journal +SyslogIdentifier=tractatus + +# Security +NoNewPrivileges=true +PrivateTmp=true + +[Install] +WantedBy=multi-user.target +``` + +**Enable and Start**: +```bash +# Reload systemd +sudo systemctl daemon-reload + +# Enable service (start on boot) +sudo systemctl enable tractatus.service + +# Start service +sudo systemctl start tractatus.service + +# Verify +sudo systemctl status tractatus.service +journalctl -u tractatus.service -f +``` + +--- + +### Configure Nginx + +#### 1. Create Nginx Configuration + +```bash +# Create site configuration +sudo nano /etc/nginx/sites-available/tractatus +``` + +**Nginx Configuration**: +```nginx +# Upstream Node.js application +upstream tractatus_app { + server 127.0.0.1:9000; + keepalive 64; +} + +# HTTP (redirect to HTTPS) +server { + listen 80; + listen [::]:80; + server_name mysy.digital www.mysy.digital; + + # Let's Encrypt verification + location /.well-known/acme-challenge/ { + root /var/www/html; + } + + # Redirect to HTTPS + location / { + return 301 https://$server_name$request_uri; + } +} + +# HTTPS +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name mysy.digital www.mysy.digital; + + # SSL certificates (Let's Encrypt) + ssl_certificate /etc/letsencrypt/live/mysy.digital/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/mysy.digital/privkey.pem; + ssl_trusted_certificate /etc/letsencrypt/live/mysy.digital/chain.pem; + + # SSL configuration (Mozilla Intermediate) + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'; + ssl_prefer_server_ciphers off; + + # SSL session cache + ssl_session_cache shared:SSL:10m; + ssl_session_timeout 10m; + + # OCSP stapling + ssl_stapling on; + ssl_stapling_verify on; + resolver 1.1.1.1 1.0.0.1 valid=300s; + resolver_timeout 5s; + + # Security headers + add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always; + add_header X-Frame-Options "DENY" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Referrer-Policy "no-referrer-when-downgrade" always; + add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always; + + # Logging + access_log /var/log/nginx/tractatus-access.log; + error_log /var/log/nginx/tractatus-error.log; + + # Root and index + root /var/www/tractatus/public; + index index.html; + + # Static files (served directly by Nginx) + location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|webp|woff|woff2|ttf|eot)$ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # API and dynamic routes (proxy to Node.js) + location /api/ { + proxy_pass http://tractatus_app; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; + proxy_read_timeout 60s; + } + + # Try static files first, then proxy to Node.js + location / { + try_files $uri $uri/ @nodejs; + } + + location @nodejs { + proxy_pass http://tractatus_app; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; + } + + # Security: Deny access to sensitive files + location ~ /\. { + deny all; + } + + location ~ /\.git { + deny all; + } + + location ~ /node_modules { + deny all; + } + + location ~ /\.env { + deny all; + } +} +``` + +**Enable Site**: +```bash +# Create symlink +sudo ln -s /etc/nginx/sites-available/tractatus /etc/nginx/sites-enabled/ + +# Remove default site +sudo rm /etc/nginx/sites-enabled/default + +# Test configuration +sudo nginx -t + +# Reload Nginx +sudo systemctl reload nginx +``` + +--- + +### SSL/TLS Setup (Let's Encrypt) + +```bash +# Obtain SSL certificate +sudo certbot --nginx -d mysy.digital -d www.mysy.digital + +# Follow prompts: +# - Enter email: john.stroh.nz@pm.me +# - Agree to terms +# - Redirect HTTP to HTTPS: Yes + +# Verify auto-renewal +sudo certbot renew --dry-run + +# Auto-renewal is configured via systemd timer +sudo systemctl list-timers | grep certbot +``` + +**Certificate Renewal** (automatic): +```bash +# Certbot creates a systemd timer for auto-renewal +# Certificates renew 30 days before expiry +# No manual intervention needed +``` + +--- + +## Security Hardening + +### Fail2ban Configuration + +```bash +# Install Fail2ban (if not already) +sudo apt install -y fail2ban + +# Create local configuration +sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local +sudo nano /etc/fail2ban/jail.local +``` + +**Jail Configuration**: +```ini +[DEFAULT] +bantime = 3600 # 1 hour ban +findtime = 600 # 10 minutes +maxretry = 5 # 5 attempts before ban + +[sshd] +enabled = true +port = 22 +filter = sshd +logpath = /var/log/auth.log + +[nginx-http-auth] +enabled = true +port = 80,443 +filter = nginx-http-auth +logpath = /var/log/nginx/error.log + +[nginx-limit-req] +enabled = true +port = 80,443 +filter = nginx-limit-req +logpath = /var/log/nginx/error.log +maxretry = 10 +``` + +**Restart**: +```bash +sudo systemctl restart fail2ban +sudo systemctl enable fail2ban + +# Verify +sudo fail2ban-client status +``` + +--- + +### MongoDB Security + +```bash +# Enable authentication +sudo nano /etc/mongod.conf +``` + +**Add**: +```yaml +security: + authorization: enabled + +net: + bindIp: 127.0.0.1 + port: 27017 +``` + +**Restart MongoDB**: +```bash +sudo systemctl restart mongod +``` + +--- + +### Automatic Security Updates + +```bash +# Install unattended-upgrades +sudo apt install -y unattended-upgrades + +# Configure +sudo dpkg-reconfigure -plow unattended-upgrades +# Select "Yes" to enable + +# Verify +sudo cat /etc/apt/apt.conf.d/20auto-upgrades +``` + +--- + +## Monitoring & Alerting + +### Log Management + +```bash +# Create log directories +sudo mkdir -p /var/log/tractatus +sudo chown tractatus:tractatus /var/log/tractatus + +# Configure logrotate +sudo nano /etc/logrotate.d/tractatus +``` + +**Logrotate Configuration**: +``` +/var/log/tractatus/*.log { + daily + rotate 7 + compress + delaycompress + missingok + notifempty + create 0640 tractatus tractatus + sharedscripts + postrotate + systemctl reload tractatus >/dev/null 2>&1 || true + endscript +} +``` + +--- + +### Uptime Monitoring Script + +```bash +# Create monitoring script +sudo nano /usr/local/bin/tractatus-healthcheck.sh +``` + +**Script**: +```bash +#!/bin/bash + +# Healthcheck endpoint +URL="https://mysy.digital/health" + +# Check if site is up +HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL) + +if [ "$HTTP_CODE" != "200" ]; then + # Alert (email to admin) + echo "Tractatus is DOWN! HTTP code: $HTTP_CODE" | \ + mail -s "ALERT: Tractatus Down" john.stroh.nz@pm.me + exit 1 +fi + +exit 0 +``` + +**Cron Job** (every 5 minutes): +```bash +# Make executable +sudo chmod +x /usr/local/bin/tractatus-healthcheck.sh + +# Add to crontab +sudo crontab -e +``` + +**Add**: +``` +*/5 * * * * /usr/local/bin/tractatus-healthcheck.sh +``` + +--- + +## Backup & Disaster Recovery + +### MongoDB Backup Script + +```bash +# Create backup directory +sudo mkdir -p /var/backups/tractatus/mongodb +sudo chown tractatus:tractatus /var/backups/tractatus/mongodb + +# Create backup script +nano /home/tractatus/backup-mongodb.sh +``` + +**Script**: +```bash +#!/bin/bash + +# Configuration +BACKUP_DIR="/var/backups/tractatus/mongodb" +DB_NAME="tractatus_prod" +DATE=$(date +%Y%m%d_%H%M%S) +RETENTION_DAYS=7 + +# Create backup +mongodump --db $DB_NAME --out $BACKUP_DIR/$DATE + +# Compress backup +tar -czf $BACKUP_DIR/tractatus_backup_$DATE.tar.gz -C $BACKUP_DIR $DATE +rm -rf $BACKUP_DIR/$DATE + +# Delete old backups +find $BACKUP_DIR -name "tractatus_backup_*.tar.gz" -mtime +$RETENTION_DAYS -delete + +echo "Backup completed: $BACKUP_DIR/tractatus_backup_$DATE.tar.gz" +``` + +**Cron Job** (daily at 2am): +```bash +chmod +x /home/tractatus/backup-mongodb.sh + +crontab -e +``` + +**Add**: +``` +0 2 * * * /home/tractatus/backup-mongodb.sh >> /var/log/tractatus/backup.log 2>&1 +``` + +--- + +### Disaster Recovery Procedure + +**Scenario**: Server failure, data loss + +**Recovery Steps**: + +1. **Provision New Server** (same specs) + +2. **Restore Application**: +```bash +# Clone repository +git clone https://github.com/your-org/tractatus.git /var/www/tractatus + +# Restore environment file +scp .env.production tractatus@:/var/www/tractatus/ +``` + +3. **Restore Database**: +```bash +# Copy backup to new server +scp tractatus_backup_YYYYMMDD.tar.gz tractatus@:/tmp/ + +# Extract and restore +tar -xzf /tmp/tractatus_backup_YYYYMMDD.tar.gz -C /tmp/ +mongorestore --db tractatus_prod /tmp/YYYYMMDD/tractatus_prod +``` + +4. **Reconfigure DNS** (if IP changed) + +5. **Verify**: +```bash +curl https://mysy.digital/health +``` + +**RTO** (Recovery Time Objective): <4 hours +**RPO** (Recovery Point Objective): 24 hours (daily backups) + +--- + +## DNS & Domain Configuration + +### Cloudflare DNS Setup + +**A Records**: +``` +Type: A +Name: @ +Content: +Proxy status: Proxied (or DNS only) +TTL: Auto +``` + +``` +Type: A +Name: www +Content: +Proxy status: Proxied (or DNS only) +TTL: Auto +``` + +**AAAA Records** (IPv6): +``` +Type: AAAA +Name: @ +Content: +Proxy status: Proxied +TTL: Auto +``` + +**MX Records** (if using custom email): +``` +Type: MX +Name: @ +Content: mail.protonmail.ch +Priority: 10 +``` + +**TXT Records** (SPF, DKIM): +``` +Type: TXT +Name: @ +Content: v=spf1 include:_spf.protonmail.ch ~all +``` + +--- + +## Environment Configuration + +### Production .env File + +**Template** (already shown above, see Deploy Application > Configure Environment) + +**Security**: +```bash +# Restrict permissions +chmod 600 /var/www/tractatus/.env.production + +# Verify +ls -l /var/www/tractatus/.env.production +# Should show: -rw------- (owner only) +``` + +--- + +## Deployment Checklist + +### Pre-Deployment + +- [ ] OVHCloud VPS provisioned (Essential tier) +- [ ] Domain registered (mysy.digital) +- [ ] Cloudflare account created (optional) +- [ ] DNS configured (A/AAAA records pointing to server) +- [ ] SSH key generated and added to server +- [ ] John Stroh has admin access + +--- + +### Server Setup + +- [ ] Ubuntu 22.04 LTS installed +- [ ] Non-root user created (tractatus) +- [ ] SSH hardened (key-only, no root) +- [ ] Firewall configured (UFW) +- [ ] Fail2ban installed and configured +- [ ] Automatic security updates enabled + +--- + +### Application Stack + +- [ ] Node.js 18 LTS installed +- [ ] MongoDB 7.x installed and running +- [ ] Nginx installed and running +- [ ] Application repository cloned +- [ ] npm dependencies installed (`npm install --production`) +- [ ] Environment file configured (.env.production) +- [ ] Database initialized (`npm run init:db`) +- [ ] Admin user created (`npm run seed:admin`) +- [ ] Tailwind CSS built (`npm run build:css`) + +--- + +### Service Configuration + +- [ ] systemd service created (tractatus.service) +- [ ] Service enabled and started +- [ ] Service logs verified (`journalctl -u tractatus`) +- [ ] Nginx configured (sites-available/tractatus) +- [ ] Nginx configuration tested (`nginx -t`) +- [ ] SSL certificates obtained (Let's Encrypt) +- [ ] HTTPS redirect working + +--- + +### Security + +- [ ] Firewall rules verified (`ufw status`) +- [ ] SSH access tested (key-only) +- [ ] MongoDB authentication enabled +- [ ] MongoDB bound to localhost only +- [ ] Application environment secrets secure (chmod 600) +- [ ] Security headers verified (browser dev tools) +- [ ] SSL Labs test: A+ rating (https://www.ssllabs.com/ssltest/) + +--- + +### Monitoring + +- [ ] Log rotation configured (logrotate) +- [ ] Uptime monitoring script installed +- [ ] Backup script configured and tested +- [ ] Email alerts configured (john.stroh.nz@pm.me) +- [ ] Plausible Analytics installed (optional, self-hosted) + +--- + +### Testing + +- [ ] Homepage loads: https://mysy.digital/ +- [ ] API health check: https://mysy.digital/health +- [ ] Document viewer: https://mysy.digital/docs-viewer.html +- [ ] Admin login: https://mysy.digital/admin/login.html +- [ ] Static assets loading (CSS, JS) +- [ ] CSP compliance (no console errors) +- [ ] Mobile responsiveness (test on phone) + +--- + +### Post-Deployment + +- [ ] DNS propagation complete (24-48 hours) +- [ ] SSL certificate auto-renewal tested (`certbot renew --dry-run`) +- [ ] Backup restore tested (disaster recovery drill) +- [ ] Performance baseline recorded (Lighthouse, WebPageTest) +- [ ] Monitoring alerts tested (trigger fake downtime) + +--- + +## Appendix: Quick Commands + +### Service Management + +```bash +# Restart application +sudo systemctl restart tractatus.service + +# View logs +sudo journalctl -u tractatus.service -f + +# Check status +sudo systemctl status tractatus.service +``` + +### Nginx + +```bash +# Test configuration +sudo nginx -t + +# Reload configuration +sudo systemctl reload nginx + +# View error log +sudo tail -f /var/log/nginx/tractatus-error.log +``` + +### MongoDB + +```bash +# Connect to database +mongosh tractatus_prod + +# Backup manually +mongodump --db tractatus_prod --out /tmp/backup + +# Restore from backup +mongorestore --db tractatus_prod /tmp/backup/tractatus_prod +``` + +### SSL + +```bash +# Renew certificates manually +sudo certbot renew + +# Check certificate expiry +sudo certbot certificates +``` + +--- + +## Revision History + +| Date | Version | Changes | +|------|---------|---------| +| 2025-10-07 | 1.0 | Initial infrastructure plan for Phase 2 | + +--- + +**Document Owner**: John Stroh +**Last Updated**: 2025-10-07 +**Next Review**: Upon deployment completion diff --git a/docs/PHASE-2-ROADMAP.md b/docs/PHASE-2-ROADMAP.md new file mode 100644 index 00000000..c4172b0f --- /dev/null +++ b/docs/PHASE-2-ROADMAP.md @@ -0,0 +1,690 @@ +# Phase 2 Roadmap: Production Deployment & AI-Powered Features + +**Project**: Tractatus AI Safety Framework Website +**Phase**: 2 of 3 +**Status**: Planning +**Created**: 2025-10-07 +**Owner**: John Stroh +**Duration**: 2-3 months (estimated) + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Phase 1 Completion Summary](#phase-1-completion-summary) +3. [Phase 2 Objectives](#phase-2-objectives) +4. [Timeline & Milestones](#timeline--milestones) +5. [Workstreams](#workstreams) +6. [Success Criteria](#success-criteria) +7. [Risk Assessment](#risk-assessment) +8. [Decision Points](#decision-points) +9. [Dependencies](#dependencies) +10. [Budget Requirements](#budget-requirements) + +--- + +## Overview + +Phase 2 transitions the Tractatus Framework from a **local prototype** (Phase 1) to a **production-ready platform** with real users and AI-powered content features. This phase demonstrates the framework's capacity to govern its own AI operations through human-oversight workflows. + +### Key Themes +- **Production Deployment**: OVHCloud hosting, domain configuration, SSL/TLS +- **AI Integration**: Claude API for blog curation, media triage, case studies +- **Dogfooding**: Tractatus framework governs all AI content generation +- **Security & Privacy**: Hardening, monitoring, privacy-respecting analytics +- **Soft Launch**: Initial user testing before public announcement (Phase 3) + +--- + +## Phase 1 Completion Summary + +**Completed**: 2025-10-07 +**Status**: ✅ All objectives achieved + +### Deliverables Completed +- ✅ MongoDB instance (port 27017, database `tractatus_dev`) +- ✅ Express application (port 9000, CSP-compliant) +- ✅ Document migration pipeline (12+ documents) +- ✅ Three audience paths (Researcher, Implementer, Advocate) +- ✅ Interactive demonstrations (27027, classification, boundary) +- ✅ Tractatus governance services (100% test coverage on core services) + - InstructionPersistenceClassifier (85.3%) + - CrossReferenceValidator (96.4%) + - BoundaryEnforcer (100%) + - ContextPressureMonitor (60.9%) + - MetacognitiveVerifier (56.1%) +- ✅ Admin dashboard with moderation workflows +- ✅ API reference documentation +- ✅ WCAG AA accessibility compliance +- ✅ Mobile responsiveness optimization +- ✅ 118 integration tests (all passing) + +### Technical Achievements +- CSP compliance: 100% (script-src 'self') +- Test coverage: 85.3%+ on Tractatus services +- Accessibility: WCAG AA compliant +- Performance: <2s page load times (local) +- Security: JWT authentication, role-based access control + +--- + +## Phase 2 Objectives + +### Primary Goals +1. **Deploy to production** on OVHCloud with domain `mysy.digital` +2. **Integrate Claude API** for AI-powered content features +3. **Implement human oversight workflows** via Tractatus framework +4. **Launch blog curation system** with moderation queue +5. **Enable media inquiry triage** with AI classification +6. **Create case study submission portal** for community contributions +7. **Soft launch** to initial user cohort (researchers, implementers) + +### Non-Goals (Deferred to Phase 3) +- ❌ Koha donation system +- ❌ Multi-language translations +- ❌ Public marketing campaign +- ❌ Community forums/discussion boards +- ❌ Mobile app development + +--- + +## Timeline & Milestones + +### Month 1: Infrastructure & Deployment (Weeks 1-4) + +**Week 1: Environment Setup** +- [ ] Provision OVHCloud VPS (specs TBD) +- [ ] Configure DNS for `mysy.digital` → production IP +- [ ] SSL/TLS certificates (Let's Encrypt) +- [ ] Firewall rules (UFW) and SSH hardening +- [ ] Create production MongoDB instance +- [ ] Set up systemd services (tractatus.service, mongodb-tractatus.service) + +**Week 2: Application Deployment** +- [ ] Deploy Express application to production +- [ ] Configure Nginx reverse proxy (port 80/443 → 9000) +- [ ] Environment variables (.env.production) +- [ ] Production logging (file rotation, syslog) +- [ ] Database migration scripts (seed production data) +- [ ] Backup automation (MongoDB dumps, code snapshots) + +**Week 3: Security Hardening** +- [ ] Fail2ban configuration (SSH, HTTP) +- [ ] Rate limiting (Nginx + application-level) +- [ ] Security headers audit (OWASP compliance) +- [ ] Vulnerability scanning (Trivy, npm audit) +- [ ] ProtonBridge email integration +- [ ] Admin notification system (email alerts) + +**Week 4: Monitoring & Testing** +- [ ] Plausible Analytics deployment (self-hosted) +- [ ] Error tracking (Sentry or self-hosted alternative) +- [ ] Uptime monitoring (UptimeRobot or self-hosted) +- [ ] Performance baseline (Lighthouse, WebPageTest) +- [ ] Load testing (k6 or Artillery) +- [ ] Disaster recovery drill (restore from backup) + +**Milestone 1**: Production environment live, accessible at `https://mysy.digital` ✅ + +--- + +### Month 2: AI-Powered Features (Weeks 5-8) + +**Week 5: Claude API Integration** +- [ ] Anthropic API key setup (production account) +- [ ] ClaudeAPI.service refactoring for production +- [ ] Rate limiting and cost monitoring +- [ ] Error handling (API failures, timeout recovery) +- [ ] Prompt templates for blog/media/cases +- [ ] Token usage tracking and alerting + +**Week 6: Blog Curation System** +- [ ] BlogCuration.service implementation + - AI topic suggestion pipeline + - Outline generation + - Citation extraction + - Draft formatting +- [ ] Human moderation workflow (approve/reject/edit) +- [ ] Blog post model (MongoDB schema) +- [ ] Blog UI (list, single post, RSS feed) +- [ ] OpenGraph/Twitter card metadata +- [ ] Seed content: 5-10 human-written posts + +**Week 7: Media Inquiry Triage** +- [ ] MediaTriage.service implementation + - Incoming inquiry classification (press, academic, commercial) + - Priority scoring (high/medium/low) + - Auto-draft response generation (for human approval) +- [ ] Media inquiry form (public-facing) +- [ ] Admin triage dashboard +- [ ] Email notification system +- [ ] Response templates + +**Week 8: Case Study Portal** +- [ ] CaseSubmission.service implementation + - Community submission form + - AI relevance analysis (Tractatus framework mapping) + - Failure mode categorization +- [ ] Case study moderation queue +- [ ] Public case study viewer +- [ ] Submission guidelines documentation +- [ ] Initial case studies (3-5 curated examples) + +**Milestone 2**: All AI-powered features operational with human oversight ✅ + +--- + +### Month 3: Polish, Testing & Soft Launch (Weeks 9-12) + +**Week 9: Governance Enforcement** +- [ ] Review all AI prompts against TRA-OPS-* policies +- [ ] Audit moderation workflows (Tractatus compliance) +- [ ] Test boundary enforcement (values decisions require humans) +- [ ] Cross-reference validator integration (AI content checks) +- [ ] MetacognitiveVerifier for complex AI operations +- [ ] Document AI decision audit trail + +**Week 10: Content & Documentation** +- [ ] Final document migration review +- [ ] Cross-reference link validation +- [ ] PDF generation pipeline (downloads section) +- [ ] Citation index completion +- [ ] Privacy policy finalization +- [ ] Terms of service drafting +- [ ] About/Contact page updates + +**Week 11: Testing & Optimization** +- [ ] End-to-end testing (user journeys) +- [ ] Performance optimization (CDN evaluation) +- [ ] Mobile testing (real devices) +- [ ] Browser compatibility (Firefox, Safari, Chrome) +- [ ] Accessibility re-audit (WCAG AA) +- [ ] Security penetration testing +- [ ] Load testing under realistic traffic + +**Week 12: Soft Launch** +- [ ] Invite initial user cohort (20-50 users) + - AI safety researchers + - Academic institutions + - Aligned organizations +- [ ] Collect feedback via structured surveys +- [ ] Monitor error rates and performance +- [ ] Iterate on UX issues +- [ ] Prepare for public launch (Phase 3) + +**Milestone 3**: Soft launch complete, feedback collected, ready for public launch ✅ + +--- + +## Workstreams + +### 1. Infrastructure & Deployment + +**Owner**: Infrastructure Lead (or John Stroh) +**Duration**: Month 1 (Weeks 1-4) + +#### Tasks +1. **Hosting Provision** + - Select OVHCloud VPS tier (see Budget Requirements) + - Provision server (Ubuntu 22.04 LTS recommended) + - Configure DNS (A records, AAAA for IPv6) + - Set up SSH key authentication (disable password auth) + +2. **Web Server Configuration** + - Install Nginx + - Configure reverse proxy (port 9000 → 80/443) + - SSL/TLS via Let's Encrypt (Certbot) + - HTTP/2 and compression (gzip/brotli) + - Security headers (CSP, HSTS, X-Frame-Options) + +3. **Database Setup** + - Install MongoDB 7.x + - Configure authentication + - Set up replication (optional for HA) + - Automated backups (daily, 7-day retention) + - Restore testing + +4. **Application Deployment** + - Git-based deployment workflow + - Environment variables management + - Systemd service configuration + - Log rotation and management + - Process monitoring (PM2 or systemd watchdog) + +5. **Security Hardening** + - UFW firewall (allow 22, 80, 443, deny all others) + - Fail2ban (SSH, HTTP) + - Unattended security updates + - Intrusion detection (optional: OSSEC, Wazuh) + - Regular security audits + +**Deliverables**: +- Production server accessible at `https://mysy.digital` +- SSL/TLS A+ rating (SSL Labs) +- Automated backup system operational +- Monitoring dashboards configured + +--- + +### 2. AI-Powered Features + +**Owner**: AI Integration Lead (or John Stroh with Claude Code) +**Duration**: Month 2 (Weeks 5-8) + +#### Tasks + +##### 2.1 Claude API Integration +- **API Setup** + - Anthropic production API key + - Rate limiting configuration (requests/min, tokens/day) + - Cost monitoring and alerting + - Fallback handling (API downtime) + +- **Service Architecture** + - `ClaudeAPI.service.js` - Core API wrapper + - Prompt template management + - Token usage tracking + - Error handling and retry logic + +##### 2.2 Blog Curation System +- **AI Pipeline** + - Topic suggestion (from AI safety news feeds) + - Outline generation + - Citation extraction and validation + - Draft formatting (Markdown) + +- **Human Oversight** + - Moderation queue integration + - Approve/Reject/Edit workflows + - Tractatus boundary enforcement (AI cannot publish without approval) + - Audit trail (who approved, when, why) + +- **Publishing** + - Blog post model (title, slug, content, author, published_at) + - Blog list UI (pagination, filtering) + - Single post viewer (comments optional) + - RSS feed generation + - Social media metadata (OpenGraph, Twitter cards) + +##### 2.3 Media Inquiry Triage +- **AI Classification** + - Inquiry type (press, academic, commercial, spam) + - Priority scoring (urgency, relevance, reach) + - Auto-draft responses (for human review) + +- **Moderation Workflow** + - Admin triage dashboard + - Email notification to John Stroh + - Response approval (before sending) + - Contact management (CRM-lite) + +##### 2.4 Case Study Portal +- **Community Submissions** + - Public submission form (structured data) + - AI relevance analysis (Tractatus applicability) + - Failure mode categorization (27027-type, boundary violation, etc.) + +- **Human Moderation** + - Case review queue + - Approve/Reject/Request Edits + - Publication workflow + - Attribution and licensing (CC BY-SA 4.0) + +**Deliverables**: +- Blog system with 5-10 initial posts +- Media inquiry form with AI triage +- Case study portal with 3-5 examples +- All AI decisions subject to human approval + +--- + +### 3. Governance & Policy + +**Owner**: Governance Lead (or John Stroh) +**Duration**: Throughout Phase 2 + +#### Tasks +1. **Create TRA-OPS-* Documents** + - TRA-OPS-0001: AI Content Generation Policy + - TRA-OPS-0002: Blog Editorial Guidelines + - TRA-OPS-0003: Media Inquiry Response Protocol + - TRA-OPS-0004: Case Study Moderation Standards + - TRA-OPS-0005: Human Oversight Requirements + +2. **Tractatus Framework Enforcement** + - Ensure all AI actions classified (STR/OPS/TAC/SYS/STO) + - Cross-reference validator integration + - Boundary enforcement (no AI values decisions) + - Audit trail for AI decisions + +3. **Legal & Compliance** + - Privacy Policy (GDPR-lite, no tracking cookies) + - Terms of Service + - Content licensing (CC BY-SA 4.0 for community contributions) + - Cookie policy (if analytics use cookies) + +**Deliverables**: +- 5+ TRA-OPS-* governance documents +- Privacy Policy and Terms of Service +- Tractatus framework audit demonstrating compliance + +--- + +### 4. Content & Documentation + +**Owner**: Content Lead (or John Stroh) +**Duration**: Month 3 (Weeks 9-12) + +#### Tasks +1. **Document Review** + - Final review of all migrated documents + - Cross-reference link validation + - Formatting consistency + - Citation completeness + +2. **Blog Launch Content** + - Write 5-10 seed blog posts (human-authored) + - Topics: Framework introduction, 27027 incident, use cases, etc. + - RSS feed implementation + - Newsletter signup (optional) + +3. **Legal Pages** + - Privacy Policy + - Terms of Service + - About page (mission, values, Te Tiriti acknowledgment) + - Contact page (ProtonMail integration) + +4. **PDF Generation** + - Automated PDF export for key documents + - Download links in UI + - Version tracking + +**Deliverables**: +- All documents reviewed and polished +- 5-10 initial blog posts published +- Privacy Policy and Terms of Service live +- PDF downloads available + +--- + +### 5. Analytics & Monitoring + +**Owner**: Operations Lead (or John Stroh) +**Duration**: Month 1 & ongoing + +#### Tasks +1. **Privacy-Respecting Analytics** + - Deploy Plausible (self-hosted) or Matomo + - No cookies, no tracking, GDPR-compliant + - Metrics: page views, unique visitors, referrers + - Geographic data (country-level only) + +2. **Error Tracking** + - Sentry (cloud) or self-hosted alternative (GlitchTip) + - JavaScript error tracking + - Server error logging + - Alerting on critical errors + +3. **Performance Monitoring** + - Uptime monitoring (UptimeRobot or self-hosted) + - Response time tracking + - Database query performance + - API usage metrics (Claude API tokens/day) + +4. **Business Metrics** + - Blog post views and engagement + - Media inquiry volume + - Case study submissions + - Admin moderation activity + +**Deliverables**: +- Analytics dashboard operational +- Error tracking with alerting +- Uptime monitoring (99.9% target) +- Monthly metrics report template + +--- + +## Success Criteria + +Phase 2 is considered **complete** when: + +### Technical Success +- [ ] Production site live at `https://mysy.digital` with SSL/TLS +- [ ] All Phase 1 features operational in production +- [ ] Blog system publishing AI-curated content (with human approval) +- [ ] Media inquiry triage system processing requests +- [ ] Case study portal accepting community submissions +- [ ] Uptime: 99%+ over 30-day period +- [ ] Performance: <3s page load (95th percentile) +- [ ] Security: No critical vulnerabilities (OWASP Top 10) + +### Governance Success +- [ ] All AI content requires human approval (0 auto-published posts) +- [ ] Tractatus framework audit shows 100% compliance +- [ ] TRA-OPS-* policies documented and enforced +- [ ] Boundary enforcer blocks values decisions by AI +- [ ] Audit trail for all AI decisions (who, what, when, why) + +### User Success +- [ ] Soft launch cohort: 20-50 users +- [ ] User satisfaction: 4+/5 average rating +- [ ] Blog engagement: 50+ readers/post average +- [ ] Media inquiries: 5+ per month +- [ ] Case study submissions: 3+ per month +- [ ] Accessibility: WCAG AA maintained + +### Business Success +- [ ] Monthly hosting costs <$100/month +- [ ] Claude API costs <$200/month +- [ ] Zero data breaches or security incidents +- [ ] Privacy policy: zero complaints +- [ ] Positive feedback from initial users + +--- + +## Risk Assessment + +### High-Risk Items + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| **Claude API costs exceed budget** | Medium | High | Implement strict rate limiting, token usage alerts, monthly spending cap | +| **Security breach (data leak)** | Low | Critical | Security audit, penetration testing, bug bounty program (Phase 3) | +| **AI generates inappropriate content** | Medium | High | Mandatory human approval, content filters, moderation queue | +| **Server downtime during soft launch** | Medium | Medium | Uptime monitoring, automated backups, disaster recovery plan | +| **GDPR/privacy compliance issues** | Low | High | Legal review, privacy-by-design, no third-party tracking | + +### Medium-Risk Items + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| **OVHCloud service disruption** | Low | Medium | Multi-region backup plan, cloud provider diversification (Phase 3) | +| **Email delivery issues (ProtonBridge)** | Medium | Low | Fallback SMTP provider, email queue system | +| **Blog content quality concerns** | Medium | Medium | Editorial guidelines, human review, reader feedback loop | +| **Performance degradation under load** | Medium | Medium | Load testing, CDN evaluation, database optimization | +| **User confusion with UI/UX** | High | Low | User testing, clear documentation, onboarding flow | + +### Low-Risk Items + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| **Domain registration issues** | Very Low | Low | Auto-renewal, registrar lock | +| **SSL certificate expiry** | Very Low | Low | Certbot auto-renewal, monitoring alerts | +| **Dependency vulnerabilities** | Medium | Very Low | Dependabot, regular npm audit | + +--- + +## Decision Points + +### Before Starting Phase 2 + +**Required Approvals from John Stroh:** + +1. **Budget Approval** (see Budget Requirements section) + - OVHCloud hosting: $30-80/month + - Claude API: $50-200/month + - Total: ~$100-300/month + +2. **Timeline Confirmation** + - Start date for Phase 2 + - Acceptable completion timeframe (2-3 months) + - Soft launch target date + +3. **Content Strategy** + - Blog editorial guidelines (TRA-OPS-0002) + - Media response protocol (TRA-OPS-0003) + - Case study moderation standards (TRA-OPS-0004) + +4. **Privacy Policy** + - Final wording for data collection + - Analytics tool selection (Plausible vs. Matomo) + - Email handling practices + +5. **Soft Launch Strategy** + - Target user cohort (researchers, implementers, advocates) + - Invitation method (email, social media) + - Feedback collection process + +### During Phase 2 + +**Interim Decisions:** + +1. **Week 2**: VPS tier selection (based on performance testing) +2. **Week 5**: Claude API usage limits (tokens/day, cost caps) +3. **Week 8**: Blog launch readiness (sufficient seed content?) +4. **Week 10**: Soft launch invite list (who to include?) +5. **Week 12**: Phase 3 go/no-go decision + +--- + +## Dependencies + +### External Dependencies + +1. **OVHCloud** + - VPS availability in preferred region + - DNS propagation (<24 hours) + - Support response time (for issues) + +2. **Anthropic** + - Claude API production access + - API stability and uptime + - Pricing stability (no unexpected increases) + +3. **Let's Encrypt** + - Certificate issuance + - Auto-renewal functionality + +4. **ProtonMail** + - ProtonBridge availability + - Email delivery reliability + +### Internal Dependencies + +1. **Phase 1 Completion** ✅ + - All features tested and working + - Clean codebase + - Documentation complete + +2. **Governance Documents** + - TRA-OPS-* policies drafted (see Task 3) + - Privacy Policy finalized + - Terms of Service drafted + +3. **Seed Content** + - 5-10 initial blog posts (human-written) + - 3-5 case studies (curated examples) + - Documentation complete + +4. **User Cohort** + - 20-50 users identified for soft launch + - Invitation list prepared + - Feedback survey drafted + +--- + +## Budget Requirements + +**See separate document: PHASE-2-COST-ESTIMATES.md** + +Summary: +- **One-time**: $50-200 (SSL, setup) +- **Monthly recurring**: $100-300 (hosting + API) +- **Total Phase 2 cost**: ~$500-1,200 (3 months) + +--- + +## Phase 2 → Phase 3 Transition + +### Exit Criteria +Phase 2 ends and Phase 3 begins when: +- All success criteria met (see Success Criteria section) +- Soft launch feedback incorporated +- Zero critical bugs outstanding +- Governance audit complete +- John Stroh approves public launch + +### Phase 3 Preview +- Public launch and marketing campaign +- Koha donation system (micropayments) +- Multi-language translations +- Community forums/discussion +- Bug bounty program +- Academic partnerships + +--- + +## Appendices + +### Appendix A: Technology Stack (Production) + +**Hosting**: OVHCloud VPS +**OS**: Ubuntu 22.04 LTS +**Web Server**: Nginx 1.24+ +**Application**: Node.js 18+, Express 4.x +**Database**: MongoDB 7.x +**SSL/TLS**: Let's Encrypt (Certbot) +**Email**: ProtonMail + ProtonBridge +**Analytics**: Plausible (self-hosted) or Matomo +**Error Tracking**: Sentry (cloud) or GlitchTip (self-hosted) +**Monitoring**: UptimeRobot or self-hosted +**AI Integration**: Anthropic Claude API (Sonnet 4.5) + +### Appendix B: Key Performance Indicators (KPIs) + +**Technical KPIs**: +- Uptime: 99.9%+ +- Response time: <3s (95th percentile) +- Error rate: <0.1% +- Security vulnerabilities: 0 critical + +**User KPIs**: +- Unique visitors: 100+/month (soft launch) +- Blog readers: 50+/post average +- Media inquiries: 5+/month +- Case submissions: 3+/month + +**Business KPIs**: +- Hosting costs: <$100/month +- API costs: <$200/month +- User satisfaction: 4+/5 +- AI approval rate: 100% (all content human-approved) + +### Appendix C: Rollback Plan + +If Phase 2 encounters critical issues: + +1. **Immediate**: Revert to Phase 1 (local prototype) +2. **Within 24h**: Root cause analysis +3. **Within 72h**: Fix deployed or timeline extended +4. **Escalation**: Consult security experts if breach suspected + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-10-07 +**Next Review**: Start of Phase 2 (TBD) +**Owner**: John Stroh +**Contributors**: Claude Code (Anthropic Sonnet 4.5) diff --git a/governance/TRA-OPS-0001-ai-content-generation-policy-v1-0.md b/governance/TRA-OPS-0001-ai-content-generation-policy-v1-0.md new file mode 100644 index 00000000..1d94182c --- /dev/null +++ b/governance/TRA-OPS-0001-ai-content-generation-policy-v1-0.md @@ -0,0 +1,374 @@ +# TRA-OPS-0001: AI Content Generation Policy v1.0 + +**Document ID**: TRA-OPS-0001 +**Version**: 1.0 +**Classification**: OPERATIONAL +**Status**: DRAFT → ACTIVE (upon Phase 2 start) +**Created**: 2025-10-07 +**Owner**: John Stroh +**Review Cycle**: Quarterly +**Next Review**: 2026-01-07 + +--- + +## Purpose + +This document establishes the operational policy governing all AI-assisted content generation on the Tractatus Framework website. It ensures that AI operations align with the Tractatus framework's core principle: **"What cannot be systematized must not be automated."** + +## Scope + +This policy applies to all content generated or assisted by AI systems, including but not limited to: +- Blog posts (topic suggestions, outlines, drafts) +- Media inquiry responses (classification, prioritization, draft responses) +- Case study analysis (relevance assessment, categorization) +- Documentation summaries +- Social media content (future) + +## Principles + +### 1. Mandatory Human Approval +**Principle**: No AI-generated content shall be published, sent, or made public without explicit human approval. + +**Implementation**: +- All AI outputs routed through moderation queue +- Two-person rule for sensitive content (admin + reviewer) +- Audit trail: who approved, when, why +- Rejection must include reason (for AI training) + +**Tractatus Mapping**: TACTICAL quadrant (execution requires pre-approval) + +--- + +### 2. Values Boundary Enforcement +**Principle**: AI systems must not make decisions involving values, ethics, or human agency. + +**Implementation**: +- BoundaryEnforcer.service validates all AI actions +- Values decisions flagged for human review +- AI may present options but not choose + +**Examples**: +- ✅ AI can suggest blog topics +- ❌ AI cannot decide editorial policy +- ✅ AI can classify inquiry priority +- ❌ AI cannot decide whether to respond + +**Tractatus Mapping**: STRATEGIC quadrant (values require human judgment per §12.1-12.7) + +--- + +### 3. Transparency & Attribution +**Principle**: Users must know when content is AI-assisted. + +**Implementation**: +- All AI-assisted content labeled "AI-Assisted, Human-Reviewed" +- Disclosure in footer or metadata +- Option to view human review notes (future) + +**Example Labels**: +```markdown +--- +AI-Assisted: Claude Sonnet 4.5 +Human Reviewer: John Stroh +Reviewed: 2025-10-15 +Changes: Minor edits for tone +--- +``` + +--- + +### 4. Quality & Accuracy Standards +**Principle**: AI-assisted content must meet the same quality standards as human-authored content. + +**Implementation**: +- Editorial guidelines (TRA-OPS-0002) apply to all content +- Fact-checking required for claims +- Citation validation (all sources verified by human) +- Tone/voice consistency with brand + +**Rejection Criteria**: +- Factual errors +- Unsupported claims +- Inappropriate tone +- Plagiarism or copyright violation +- Hallucinated citations + +--- + +### 5. Privacy & Data Protection +**Principle**: AI systems must not process personal data without consent. + +**Implementation**: +- No user data sent to Claude API without anonymization +- Media inquiries: strip PII before AI analysis +- Case submissions: explicit consent checkbox +- Audit logs: no personal data retention + +**Compliance**: GDPR-lite principles (even if not EU-based) + +--- + +### 6. Cost & Resource Management +**Principle**: AI usage must be cost-effective and sustainable. + +**Implementation**: +- Monthly budget cap: $200/month (see TRA-OPS-0005) +- Rate limiting: 1000 requests/day max +- Caching: 30-day TTL for identical queries +- Monitoring: alert if >80% of budget used + +**Governance**: Quarterly cost review, adjust limits as needed + +--- + +## AI System Inventory + +### Approved AI Systems + +| System | Provider | Model | Purpose | Status | +|--------|----------|-------|---------|--------| +| **Claude API** | Anthropic | Sonnet 4.5 | Blog curation, media triage, case analysis | APPROVED | + +### Future Considerations + +| System | Provider | Purpose | Status | +|--------|----------|---------|--------| +| **GPT-4** | OpenAI | Fallback for Claude outages | EVALUATION | +| **LLaMA 3** | Meta | Self-hosted alternative | RESEARCH | + +**Approval Process**: Any new AI system requires: +1. Technical evaluation (accuracy, cost, privacy) +2. Governance review (Tractatus compliance) +3. John Stroh approval +4. 30-day pilot period + +--- + +## Operational Workflows + +### Blog Post Generation Workflow + +```mermaid +graph TD + A[News Feed Ingestion] --> B[AI Topic Suggestion] + B --> C[Human Approval Queue] + C -->|Approved| D[AI Outline Generation] + C -->|Rejected| Z[End] + D --> E[Human Review & Edit] + E -->|Accept| F[Human Writes Draft] + E -->|Reject| Z + F --> G[Final Human Approval] + G -->|Approved| H[Publish] + G -->|Rejected| Z +``` + +**Key Decision Points**: +1. **Topic Approval**: Human decides if topic is valuable (STRATEGIC) +2. **Outline Review**: Human edits for accuracy/tone (OPERATIONAL) +3. **Draft Approval**: Human decides to publish (STRATEGIC) + +--- + +### Media Inquiry Workflow + +```mermaid +graph TD + A[Inquiry Received] --> B[Strip PII] + B --> C[AI Classification] + C --> D[AI Priority Scoring] + D --> E[AI Draft Response] + E --> F[Human Review Queue] + F -->|Approve & Send| G[Send Response] + F -->|Edit & Send| H[Human Edits] + F -->|Reject| Z[End] + H --> G +``` + +**Key Decision Points**: +1. **Classification Review**: Human verifies AI categorization (OPERATIONAL) +2. **Send Decision**: Human decides whether to respond (STRATEGIC) + +--- + +### Case Study Workflow + +```mermaid +graph TD + A[Community Submission] --> B[Consent Check] + B -->|No Consent| Z[Reject] + B -->|Consent| C[AI Relevance Analysis] + C --> D[AI Tractatus Mapping] + D --> E[Human Moderation Queue] + E -->|Approve| F[Publish to Portal] + E -->|Request Edits| G[Contact Submitter] + E -->|Reject| H[Notify with Reason] +``` + +**Key Decision Points**: +1. **Consent Validation**: Automated check (SYSTEM) +2. **Relevance Assessment**: Human verifies AI analysis (OPERATIONAL) +3. **Publication Decision**: Human decides to publish (STRATEGIC) + +--- + +## Human Oversight Requirements + +### Minimum Oversight Levels + +| Content Type | Minimum Reviewers | Review SLA | Escalation | +|--------------|-------------------|------------|------------| +| **Blog Posts** | 1 (admin) | 48 hours | N/A | +| **Media Inquiries (High Priority)** | 1 (admin) | 4 hours | John Stroh | +| **Media Inquiries (Low Priority)** | 1 (admin) | 7 days | N/A | +| **Case Studies** | 1 (admin) | 7 days | N/A | +| **Documentation Changes** | 1 (admin) | 14 days | John Stroh | + +### Reviewer Qualifications + +**Admin Reviewer** (minimum requirements): +- Understands Tractatus framework +- Technical background (AI/ML familiarity) +- Editorial experience (writing, fact-checking) +- Authorized by John Stroh + +**Future**: Multiple reviewer roles (technical, editorial, legal) + +--- + +## Audit & Compliance + +### Audit Trail Requirements + +All AI-assisted content must log: +- **Input**: What was sent to AI (prompt + context) +- **Output**: Raw AI response (unedited) +- **Review**: Human changes (diff) +- **Decision**: Approve/reject + reason +- **Metadata**: Reviewer, timestamp, model version + +**Retention**: 2 years minimum + +### Compliance Monitoring + +**Monthly Review**: +- AI approval rate (target: 70-90%) +- Rejection reasons (categorized) +- Cost vs. budget +- SLA compliance + +**Quarterly Review**: +- Policy effectiveness +- User feedback on AI content quality +- Boundary violations (should be 0) +- Cost-benefit analysis + +**Annual Review**: +- Full policy revision +- AI system evaluation +- Governance alignment audit + +--- + +## Error Handling & Incidents + +### AI System Failures + +**Scenario**: Claude API unavailable + +**Response**: +1. Graceful degradation: disable AI features +2. Manual workflows: admins handle all tasks +3. User notification: "AI features temporarily unavailable" +4. Post-mortem: document incident, adjust SLAs + +### Content Quality Issues + +**Scenario**: AI-generated content contains factual error + +**Response**: +1. Immediate retraction/correction (if published) +2. Root cause analysis: prompt issue, AI hallucination, review failure? +3. Process update: improve review checklist +4. Reviewer training: flag similar errors + +### Boundary Violations + +**Scenario**: AI makes values decision without human approval + +**Response**: +1. **CRITICAL INCIDENT**: Escalate to John Stroh immediately +2. Rollback: revert to manual workflow +3. Investigation: How did BoundaryEnforcer fail? +4. System audit: Test all boundary checks +5. Policy review: Update TRA-OPS-0001 + +**Tractatus Mandate**: Zero tolerance for boundary violations + +--- + +## Revision & Amendment Process + +### Minor Revisions (v1.0 → v1.1) +- Typos, clarifications, formatting +- Approval: Admin reviewer +- Notification: Email to stakeholders + +### Major Revisions (v1.0 → v2.0) +- Policy changes, new workflows, scope expansion +- Approval: John Stroh +- Review: 30-day comment period +- Notification: Blog post announcement + +### Emergency Amendments +- Security/privacy issues requiring immediate change +- Approval: John Stroh (verbal, documented within 24h) +- Review: Retrospective within 7 days + +--- + +## Related Documents + +**Strategic**: +- STR-VAL-0001: Core Values & Principles (source: sydigital) +- STR-GOV-0001: Strategic Review Protocol (source: sydigital) +- STR-GOV-0002: Values Alignment Framework (source: sydigital) + +**Operational** (Tractatus-specific): +- TRA-OPS-0002: Blog Editorial Guidelines +- TRA-OPS-0003: Media Inquiry Response Protocol +- TRA-OPS-0004: Case Study Moderation Standards +- TRA-OPS-0005: Human Oversight Requirements + +**Technical**: +- API Documentation: `/docs/api-reference.html` +- Tractatus Framework Specification: `/docs/technical-proposal.md` + +--- + +## Glossary + +**AI-Assisted Content**: Content where AI contributed to generation (topic, outline, draft) but human made final decisions and edits. + +**Boundary Violation**: AI system making a decision in STRATEGIC quadrant (values, ethics, policy) without human approval. + +**Human Approval**: Explicit action by authorized reviewer to publish/send AI-assisted content. + +**Moderation Queue**: System where AI outputs await human review before publication. + +**Values Decision**: Any decision involving ethics, privacy, user agency, editorial policy, or mission alignment. + +--- + +## Approval + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| **Policy Owner** | John Stroh | [Pending] | [TBD] | +| **Technical Reviewer** | Claude Code | [Pending] | 2025-10-07 | +| **Final Approval** | John Stroh | [Pending] | [TBD] | + +--- + +**Status**: DRAFT (awaiting John Stroh approval to activate) +**Effective Date**: Upon Phase 2 deployment +**Next Review**: 2026-01-07 (3 months post-activation) diff --git a/governance/TRA-OPS-0002-blog-editorial-guidelines-v1-0.md b/governance/TRA-OPS-0002-blog-editorial-guidelines-v1-0.md new file mode 100644 index 00000000..9f29591b --- /dev/null +++ b/governance/TRA-OPS-0002-blog-editorial-guidelines-v1-0.md @@ -0,0 +1,492 @@ +# TRA-OPS-0002: Blog Editorial Guidelines v1.0 + +**Document ID**: TRA-OPS-0002 +**Version**: 1.0 +**Classification**: OPERATIONAL +**Status**: DRAFT → ACTIVE (upon Phase 2 start) +**Created**: 2025-10-07 +**Owner**: John Stroh +**Review Cycle**: Quarterly +**Next Review**: 2026-01-07 +**Parent Policy**: TRA-OPS-0001 (AI Content Generation Policy) + +--- + +## Purpose + +This document establishes editorial guidelines for the Tractatus Framework blog, ensuring all content (human-authored and AI-assisted) aligns with the project's mission, values, and quality standards. + +## Scope + +Applies to all blog content published on `mysy.digital/blog`, including: +- Technical articles +- Framework updates +- Case study analyses +- AI safety commentary +- Community contributions + +--- + +## Editorial Mission + +**Mission**: Advance AI safety through accessible, rigorous, and actionable content that demonstrates the Tractatus framework's principles in practice. + +**Target Audiences**: +1. **Researchers**: Academic depth, citations, formal rigor +2. **Implementers**: Practical guides, code examples, integration patterns +3. **Advocates**: Plain language, real-world impact, policy implications + +--- + +## Content Principles + +### 1. Accuracy & Rigor +**Standard**: All factual claims must be supported by credible sources. + +**Requirements**: +- Citations for all non-obvious claims +- Links to primary sources (not secondary summaries) +- Explicit acknowledgment of uncertainty ("likely," "may," "appears to") +- Corrections published prominently if errors discovered + +**AI Guidance**: AI-generated content often hallucinates citations. **All citations must be manually verified by human reviewer.** + +--- + +### 2. Accessibility +**Standard**: Content should be understandable to target audience without sacrificing accuracy. + +**Requirements**: +- Define technical terms on first use +- Link to glossary for framework-specific terminology +- Provide examples for abstract concepts +- Avoid jargon unless necessary (then explain) + +**Balance**: Academic rigor without academic gatekeeping. + +--- + +### 3. Transparency +**Standard**: Readers should understand how content was created. + +**Requirements**: +- AI-assisted posts labeled: "AI-Assisted, Human-Reviewed" +- Human-authored posts labeled: "Human-Authored" +- Guest posts: Author bio + disclaimer +- Sponsored content: Not allowed (ever) + +**Example Attribution**: +```markdown +--- +Author: John Stroh +AI-Assisted: Claude Sonnet 4.5 (topic suggestion, outline) +Human Review: 2025-10-15 +Changes: Rewrote introduction, added 3 examples, verified all citations +--- +``` + +--- + +### 4. Intellectual Honesty +**Standard**: Acknowledge limitations, counterarguments, and uncertainty. + +**Requirements**: +- Address obvious objections to arguments +- Acknowledge when evidence is limited +- Link to opposing viewpoints (with fair summary) +- Update posts when new evidence emerges + +**Tractatus Alignment**: Humility in knowledge claims (§3.1-3.9). + +--- + +### 5. Respect & Inclusion +**Standard**: Content should be respectful, inclusive, and accessible. + +**Requirements**: +- Avoid ableist, racist, sexist, or exclusionary language +- Use gender-neutral language unless referring to specific individuals +- Provide alt text for images +- Caption videos (future) +- Acknowledge diverse perspectives in AI safety (Western, non-Western, indigenous) + +**Te Tiriti Alignment**: Respect Māori data sovereignty principles (reference when relevant). + +--- + +## Content Categories + +### 1. Framework Updates +**Purpose**: Announce changes to Tractatus framework (new services, governance updates) + +**Format**: +- Summary of change (2-3 sentences) +- Motivation (why the change?) +- Technical details (for implementers) +- Migration guide (if breaking change) +- Discussion/feedback invitation + +**Frequency**: As needed (1-2/month typical) + +**Example Topics**: +- "ContextPressureMonitor v2.0: Weighted Pressure Scoring" +- "New Governance Document: TRA-OPS-0003 Media Protocol" + +--- + +### 2. Case Study Analysis +**Purpose**: Analyze real-world AI failures through Tractatus lens + +**Format**: +- Incident summary (what happened?) +- Failure mode analysis (why did it happen?) +- Tractatus mapping (which boundary was crossed?) +- Prevention strategy (how framework prevents this) +- Lessons learned + +**Frequency**: 2-4/month + +**Example Topics**: +- "The 27027 Incident Revisited: Instruction Persistence Failure" +- "ChatGPT Jailbreaks: Boundary Enforcement vs. Prompt Injection" + +--- + +### 3. Technical Deep Dives +**Purpose**: Explain framework implementation details for developers + +**Format**: +- Problem statement (what are we solving?) +- Architecture overview (high-level design) +- Code examples (production-ready) +- Testing strategies +- Performance considerations + +**Frequency**: 1-2/month + +**Example Topics**: +- "Implementing CrossReferenceValidator: Instruction Database Design" +- "BoundaryEnforcer Performance: Zero-Overhead Runtime Checks" + +--- + +### 4. AI Safety Commentary +**Purpose**: Discuss broader AI safety issues through Tractatus perspective + +**Format**: +- Current event/trend summary +- Tractatus analysis (what does framework say?) +- Broader implications +- Call to action (if appropriate) + +**Frequency**: 1-2/month + +**Example Topics**: +- "AGI Timelines & Tractatus: Why Architecture Matters Now" +- "EU AI Act & Boundary Enforcement: Regulatory Alignment" + +--- + +## Writing Standards + +### Style Guide + +**Tone**: +- Professional but conversational +- Confident but humble +- Rigorous but accessible +- Passionate but not preachy + +**Voice**: +- Active voice preferred ("We implemented..." not "It was implemented...") +- First-person plural for Tractatus team ("We believe...") +- Second-person for reader ("You can integrate...") + +**Format**: +- Headings: Title Case (## This Is a Heading) +- Lists: Sentence case (- First item) +- Code: Inline `backticks`, blocks with language tags +- Emphasis: **Bold** for important, *italic* for emphasis + +**Length**: +- Minimum: 500 words (short updates) +- Typical: 1000-2000 words +- Maximum: 5000 words (deep dives) + +--- + +### Structure Template + +**All posts should follow this structure**: + +```markdown +# Post Title (Specific, Keyword-Rich) + +**Author**: Name +**Date**: YYYY-MM-DD +**Reading Time**: X min (auto-calculated) +**Category**: [Framework Update | Case Study | Technical | Commentary] + +## Summary (TL;DR) +2-3 sentence summary for skimmers. + +## Introduction +Hook + context + thesis statement. + +## Main Content +3-5 sections with descriptive headings. + +## Conclusion +Key takeaways + call to action (optional). + +## Further Reading +- Links to related posts +- External resources +- Framework docs + +## Citations +[1] Source Title, Author, Year, URL +[2] ... + +--- + +*AI-Assisted: [Yes/No]. Human Review: [Date].* +``` + +--- + +## AI-Assisted Content Workflow + +### Topic Suggestion Phase + +**AI Role**: Suggest 5-10 topics weekly based on AI safety news. + +**Input to AI**: +- Recent news feed (Hacker News, arXiv, AI safety forums) +- Tractatus docs (framework context) +- Previous blog posts (avoid duplicates) + +**AI Output**: +- Topic suggestions (1-sentence each) +- Relevance score (0-1) +- Target audience (researcher/implementer/advocate) +- Estimated complexity (low/medium/high) + +**Human Review**: +- Select 1-3 topics for outline generation +- Reject off-brand or low-value topics +- Add topics manually if AI misses obvious ones + +**SLA**: Weekly (Fridays) + +--- + +### Outline Generation Phase + +**AI Role**: Generate detailed outline for approved topics. + +**Input to AI**: +- Approved topic +- Editorial guidelines (this document) +- Target audience +- Suggested length (500-5000 words) + +**AI Output**: +- Title + subtitle +- Introduction outline (key points) +- 3-5 main sections (with subsections) +- Conclusion outline +- Suggested citations (to be verified) + +**Human Review**: +- Verify outline structure +- Add/remove/reorder sections +- Flag any factual concerns +- Approve for human drafting + +**SLA**: 48 hours + +--- + +### Draft Writing Phase + +**AI Role**: None. **Human writes the actual draft.** + +**Rationale**: Blog content is STRATEGIC (editorial voice, values communication). AI can assist with structure, but human must do the writing. + +**Exception**: Technical code examples may be AI-generated, but human must test and verify. + +--- + +### Final Review Phase + +**AI Role**: Optional proofreading (grammar, clarity). + +**Human Role**: Final fact-check, citation verification, tone check. + +**Approval**: Admin reviewer (or John Stroh for sensitive topics). + +**SLA**: 24 hours before scheduled publish. + +--- + +## Citation Standards + +### Citation Format + +**Use APA-lite style**: + +```markdown +## Citations + +[1] Wittgenstein, L. (1921). *Tractatus Logico-Philosophicus*. London: Routledge & Kegan Paul. https://example.com + +[2] Anthropic. (2024). Claude 3 Model Card. Retrieved from https://www.anthropic.com/claude + +[3] Bostrom, N. (2014). *Superintelligence: Paths, Dangers, Strategies*. Oxford University Press. +``` + +**In-text references**: Use superscript numbers: "As Wittgenstein argued[1], the limits of language..." + +--- + +### Source Quality Hierarchy + +**Preferred Sources**: +1. Peer-reviewed academic papers (journals, conferences) +2. Technical reports from reputable organizations (OpenAI, Anthropic, DeepMind) +3. Government/regulatory documents (EU AI Act, NIST guidelines) +4. Established news outlets (NY Times, Wired, Ars Technica) + +**Acceptable Sources** (with caveats): +5. Blog posts from AI safety researchers (personal, but expert) +6. Social media (Twitter/X) from verified experts (screenshot + archive) + +**Unacceptable Sources**: +7. Wikipedia (use as starting point, cite original sources) +8. Anonymous forums (4chan, Reddit unless verified expert) +9. AI-generated content (ChatGPT output is not a source) +10. Satirical/parody sites (The Onion, unless discussing satire) + +**AI Guidance**: AI often cites sources that don't exist. **ALWAYS verify every citation manually.** + +--- + +## Prohibited Content + +**Absolutely Not Allowed**: +- Plagiarism (even with AI assistance) +- Hate speech, discrimination, harassment +- Misinformation (intentional false claims) +- Sponsored content (hidden advertising) +- Political endorsements (organizational neutrality) +- Personal attacks on individuals/organizations +- Copyright violation (images, code without permission) + +**Editorial Judgment Required**: +- Controversial topics (AI risk levels, AGI timelines) +- Criticism of specific AI companies (factual, balanced) +- Speculative scenarios (clearly labeled as speculation) + +--- + +## Comments & Community Engagement + +**Phase 2**: Comments disabled initially (focus on publishing quality content). + +**Phase 3**: Comments enabled with moderation. + +**Social Media**: Posts shared on Twitter/X, Mastodon (future). + +**Engagement Guidelines**: +- Respond to substantive questions/critiques +- Acknowledge errors promptly +- Update posts when new evidence emerges +- Link to discussions (Hacker News, LessWrong) but don't feed trolls + +--- + +## Content Calendar + +### Publishing Schedule + +**Target**: 2-4 posts/month (Phase 2 soft launch) + +**Days**: Tuesdays & Thursdays (10am NZT) + +**Planning Horizon**: 2 weeks ahead (outline approved) + +--- + +### Example Editorial Calendar (Phase 2 Month 1) + +| Week | Topic | Category | Author | Status | +|------|-------|----------|--------|--------| +| W1 | "Introducing Tractatus Blog" | Framework Update | John | Draft | +| W1 | "The 27027 Incident" | Case Study | AI-assisted | Outline | +| W2 | "CrossReferenceValidator Deep Dive" | Technical | AI-assisted | Planned | +| W3 | "Why AI Safety Needs Architecture" | Commentary | John | Idea | +| W4 | "BoundaryEnforcer in Practice" | Technical | AI-assisted | Idea | + +--- + +## Performance Metrics + +### Success Metrics (Phase 2) + +**Engagement**: +- Average readers/post: 50+ (soft launch target) +- Average reading time: >2 minutes (indicates engagement) +- Social shares: 10+ per post + +**Quality**: +- Citation accuracy: 100% (zero broken/fake citations) +- Corrections rate: <5% (fewer than 1 in 20 posts need correction) +- User feedback: 4+/5 average rating (future) + +**Production**: +- Publishing consistency: 8+ posts/month +- Time to publish: <7 days from outline approval +- AI approval rate: 70-90% (outlines accepted) + +--- + +## Revision & Updates + +### Post Updates + +**Minor Edits** (typos, clarifications): +- Edit in place, no notification + +**Factual Corrections**: +- Add correction note at top: "UPDATE (YYYY-MM-DD): Corrected claim about..." +- Strikethrough incorrect text, add correct text +- Update changelog at bottom + +**Major Revisions**: +- Consider new post: "Revisiting [Topic]: What We Got Wrong" +- Link from original post + +--- + +## Related Documents + +- TRA-OPS-0001: AI Content Generation Policy (parent) +- TRA-OPS-0005: Human Oversight Requirements +- STR-VAL-0001: Core Values & Principles (sydigital) + +--- + +## Approval + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| **Policy Owner** | John Stroh | [Pending] | [TBD] | +| **Technical Reviewer** | Claude Code | [Pending] | 2025-10-07 | +| **Final Approval** | John Stroh | [Pending] | [TBD] | + +--- + +**Status**: DRAFT (awaiting John Stroh approval) +**Effective Date**: Upon first blog post publication (Phase 2) +**Next Review**: 2026-01-07 diff --git a/governance/TRA-OPS-0003-media-inquiry-response-protocol-v1-0.md b/governance/TRA-OPS-0003-media-inquiry-response-protocol-v1-0.md new file mode 100644 index 00000000..d5281e4e --- /dev/null +++ b/governance/TRA-OPS-0003-media-inquiry-response-protocol-v1-0.md @@ -0,0 +1,473 @@ +# TRA-OPS-0003: Media Inquiry Response Protocol v1.0 + +**Document ID**: TRA-OPS-0003 +**Version**: 1.0 +**Classification**: OPERATIONAL +**Status**: DRAFT → ACTIVE (upon Phase 2 start) +**Created**: 2025-10-07 +**Owner**: John Stroh +**Review Cycle**: Quarterly +**Next Review**: 2026-01-07 +**Parent Policy**: TRA-OPS-0001 (AI Content Generation Policy) + +--- + +## Purpose + +This document establishes the protocol for handling media inquiries (press, academic, commercial) using AI-assisted triage while ensuring human oversight for all external communications. + +## Scope + +Applies to all incoming inquiries received via: +- Contact form (`/contact`) +- Email (`contact@mysy.digital` → `john.stroh.nz@pm.me`) +- Social media (future) +- Conference/event requests + +--- + +## Principles + +### 1. Responsiveness +**Commitment**: Acknowledge all legitimate inquiries within 48 hours (business days). + +**AI Assistance**: AI triages and drafts acknowledgments, but human approves all sent messages. + +--- + +### 2. Privacy Protection +**Commitment**: No personal data processed by AI without anonymization. + +**Implementation**: +- Strip PII before sending to Claude API +- Anonymize email addresses (sender@example.com → REDACTED) +- Remove phone numbers, physical addresses +- Audit trail: who accessed inquiry, when + +--- + +### 3. Human Decision-Making +**Commitment**: Humans decide whether and how to respond to inquiries. + +**AI Role**: Classification, prioritization, draft suggestions only. + +**Tractatus Boundary**: AI cannot decide to send responses (STRATEGIC quadrant - external communication is values-laden). + +--- + +## Inquiry Classification + +### Categories + +| Category | Description | Priority | Response SLA | +|----------|-------------|----------|--------------| +| **Press** | Journalists, media outlets, news organizations | HIGH | 4 hours (business) | +| **Academic** | Researchers, universities, conferences | MEDIUM | 48 hours | +| **Commercial** | Companies, startups, integration partners | MEDIUM | 7 days | +| **Community** | Individual users, hobbyists, students | LOW | 14 days | +| **Spam** | Unsolicited marketing, irrelevant | IGNORE | - | + +--- + +### AI Classification Criteria + +**Input to AI**: +```markdown +Classify this inquiry into: Press, Academic, Commercial, Community, or Spam. + +Inquiry Text (anonymized): +[REDACTED_TEXT] + +Context: +- Website: mysy.digital (AI safety framework) +- Audience: Researchers, implementers, advocates +- Mission: Advance AI safety through architectural constraints + +Output format: +Category: [Press|Academic|Commercial|Community|Spam] +Confidence: [0.0-1.0] +Priority: [HIGH|MEDIUM|LOW|IGNORE] +Reasoning: [2-sentence explanation] +``` + +**Human Override**: Admin can reclassify if AI is wrong. + +--- + +## Priority Scoring + +### Factors + +AI scores inquiries based on: + +| Factor | Weight | Description | +|--------|--------|-------------| +| **Reach** | 30% | Audience size (NYT > Local Blog) | +| **Relevance** | 25% | AI safety focus (direct > tangential) | +| **Urgency** | 20% | Deadline (24h > 2 weeks) | +| **Alignment** | 15% | Values alignment (AI safety advocate > adversary) | +| **Opportunity** | 10% | Partnership, funding, exposure potential | + +**Score Range**: 0.0 (lowest) to 1.0 (highest) + +**Priority Thresholds**: +- **HIGH** (0.7-1.0): Immediate attention (alert John Stroh) +- **MEDIUM** (0.4-0.7): Standard workflow +- **LOW** (0.0-0.4): Best-effort response + +--- + +## Response Workflow + +### Step 1: Inquiry Reception + +**Trigger**: Form submission or email received + +**Automated Actions**: +1. Log to database (`media_inquiries` collection) +2. Strip PII (email → REDACTED) +3. Send to AI for classification +4. Alert admin (email notification) + +**No AI Decision**: System does NOT auto-respond (even acknowledgment). + +--- + +### Step 2: AI Classification & Triage + +**AI Task**: Analyze inquiry and generate: +- Category (Press, Academic, Commercial, Community, Spam) +- Priority score (0.0-1.0) +- Suggested response template +- Key points to address +- Deadline (if mentioned) + +**Output Example**: +```json +{ + "category": "Press", + "confidence": 0.92, + "priority": "HIGH", + "priority_score": 0.85, + "reasoning": "Request from TechCrunch journalist, 48h deadline for AI safety feature article.", + "suggested_template": "press_high_priority", + "key_points": [ + "Framework overview", + "27027 incident prevention", + "Interview availability" + ], + "deadline": "2025-10-10" +} +``` + +--- + +### Step 3: Human Review (Triage Dashboard) + +**Admin Dashboard**: `/admin/media-triage` + +**UI Elements**: +- Inquiry list (sorted by priority score) +- Color-coded priorities (red=HIGH, yellow=MEDIUM, green=LOW) +- AI classification (with confidence %) +- Draft response (AI-generated, editable) +- Action buttons: Approve & Send | Edit | Ignore | Archive + +**Human Actions**: +1. Review AI classification (override if wrong) +2. Review priority score (adjust if needed) +3. Review draft response +4. Decide: Send, Edit, Ignore, or Escalate + +--- + +### Step 4: Draft Response Generation + +**AI Task**: Generate draft response based on template + context. + +**Input to AI**: +```markdown +Generate a response to this [CATEGORY] inquiry. + +Context: +- Inquiry: [ANONYMIZED_TEXT] +- Category: [Press/Academic/Commercial/Community] +- Priority: [HIGH/MEDIUM/LOW] +- Template: [Template Name] +- Key Points: [List from classification] + +Guidelines: +- Professional, friendly tone +- Concise (2-3 paragraphs max) +- Include relevant links (docs, demos) +- Offer next steps (interview, meeting, resources) +- Sign off: "Best regards, Tractatus Team" + +Output: Plain text email (no HTML) +``` + +**Human Review**: +- Fact-check all claims +- Adjust tone (friendlier, more formal, etc.) +- Add/remove details +- Personalize (use requester's name, reference specifics) + +--- + +### Step 5: Approval & Sending + +**Approval**: +- Admin reviewer clicks "Approve & Send" +- System logs approval (who, when, what changed from AI draft) +- Email sent from `contact@mysy.digital` (ProtonBridge) + +**Follow-up**: +- Set reminder for follow-up (if no response in 7 days) +- Track conversation thread +- Archive when resolved + +--- + +## Response Templates + +### Template: Press (High Priority) + +**Subject**: Re: [Original Subject] + +``` +Hi [Name], + +Thank you for your inquiry about the Tractatus Framework. We'd be happy to discuss how architectural constraints can advance AI safety. + +The Tractatus Framework is the world's first production implementation of AI safety through architectural boundaries (rather than behavioral alignment). Our key innovation is the principle: "What cannot be systematized must not be automated." + +Key points for your article: +- [Key Point 1 from AI analysis] +- [Key Point 2 from AI analysis] +- [Key Point 3 from AI analysis] + +I'm available for an interview on [Availability]. You can also explore our interactive demonstrations at https://mysy.digital/demos. + +Best regards, +The Tractatus Team +[John Stroh, Founder] +``` + +--- + +### Template: Academic (Medium Priority) + +**Subject**: Re: Research Collaboration - Tractatus Framework + +``` +Dear [Name], + +Thank you for your interest in the Tractatus Framework for your research on [Topic]. + +We're actively seeking academic partnerships to validate and extend the framework. Our current focus areas include: +- Boundary enforcement mechanisms +- Cross-reference validation for instruction persistence +- Context pressure monitoring for degraded AI operation detection + +For your [Conference/Paper], we can provide: +- Technical documentation: https://mysy.digital/docs +- Code examples: https://github.com/tractatus (future) +- Consultation: [Contact Information] + +I'd be happy to discuss collaboration opportunities. Please let me know your timeline and specific research questions. + +Best regards, +The Tractatus Team +``` + +--- + +### Template: Commercial (Medium Priority) + +**Subject**: Re: Integration Inquiry - Tractatus Framework + +``` +Hi [Name], + +Thank you for your interest in integrating the Tractatus Framework into [Company/Product]. + +The framework is currently in Phase 2 development (soft launch). We expect production-ready packages in [Timeframe]. + +For early adopters, we offer: +- Implementation consultation +- Custom integration support +- Co-development partnerships (aligned organizations) + +To get started: +1. Review the implementation guide: https://mysy.digital/implementer +2. Explore the API reference: https://mysy.digital/api +3. Schedule a technical discussion: [Calendar Link] + +Best regards, +The Tractatus Team +``` + +--- + +### Template: Community (Low Priority) + +**Subject**: Re: [Original Subject] + +``` +Hi [Name], + +Thanks for reaching out! We're glad you're interested in the Tractatus Framework. + +For [Question/Topic], I recommend: +- [Relevant documentation link] +- [Demo link] +- [Case study or blog post link] + +If you have specific questions after reviewing these resources, feel free to follow up or join our community discussions at [Future: Discord/Forum]. + +Best regards, +The Tractatus Team +``` + +--- + +## Escalation Procedure + +### When to Escalate to John Stroh + +**Immediate Escalation (within 1 hour)**: +- Major media outlet (NY Times, Wired, BBC, etc.) +- Government/regulatory inquiry +- Legal threat or concern +- Security/privacy breach report +- Criticism/controversy requiring official response + +**Standard Escalation (within 24 hours)**: +- Partnership opportunities (funding, collaboration) +- Speaking invitations (conferences, podcasts) +- Ambiguous requests (not clear what they want) + +**Escalation Process**: +1. Admin flags inquiry as "Escalation Required" +2. Email sent to John Stroh with: + - Original inquiry (full text) + - AI analysis + - Admin notes + - Suggested response (if any) +3. John Stroh responds with: + - Approval to send draft + - Revised response + - "I'll handle this personally" (admin archives) + +--- + +## Spam & Abuse Handling + +### Spam Indicators (AI Detection) + +- Generic language ("Dear Sir/Madam") +- Unsolicited sales pitches +- Cryptocurrency, SEO, marketing services +- Requests for backlinks, guest posts +- Obvious phishing attempts + +**Action**: Auto-classify as "Spam", flag for human review (in case of false positive). + +**No Response**: Spam inquiries are archived without response. + +--- + +### Abuse Handling + +**Definition**: Harassment, threats, hate speech + +**Immediate Action**: +1. Flag inquiry as "Abuse" +2. Do NOT respond +3. Alert John Stroh +4. Document incident +5. Block sender (if persistent) + +**Legal Threshold**: Threats of violence → report to authorities (NZ police). + +--- + +## Privacy & Data Retention + +### PII Handling + +**Before AI Processing**: +- Strip email addresses: `sender@example.com` → `REDACTED_EMAIL` +- Strip phone numbers: `+64 21 123 4567` → `REDACTED_PHONE` +- Strip physical addresses +- Keep first name only (for personalization) + +**After AI Processing**: +- Store AI-generated draft (no PII) +- Store final response sent (full email for audit) + +### Data Retention + +| Data Type | Retention Period | Reason | +|-----------|------------------|--------| +| **Original Inquiry** | 2 years | Legal/audit | +| **AI Classification** | 2 years | Training/improvement | +| **Draft Response** | 2 years | Audit trail | +| **Sent Response** | Indefinite | Legal/historical | +| **Spam Inquiries** | 90 days | Reduce false positives | + +**GDPR Compliance**: Inquiry senders can request deletion (email contact@mysy.digital). + +--- + +## Performance Metrics + +### Response Quality + +**Metrics**: +- Response time: % within SLA (target: 95%) +- Classification accuracy: % AI correct (target: 90%) +- Priority accuracy: % AI scoring matches human (target: 85%) +- Response rate: % inquiries receiving a response (target: 100% non-spam) + +### Engagement + +**Metrics**: +- Follow-up rate: % inquiries leading to further conversation +- Partnership rate: % commercial inquiries → partnership +- Media coverage: # articles/mentions from press inquiries + +--- + +## Revision & Updates + +**Review Cycle**: Quarterly + +**Update Triggers**: +- Classification accuracy <80% (templates need improvement) +- Response SLA missed >10% of time (workflow issue) +- User complaints about response quality + +--- + +## Related Documents + +- TRA-OPS-0001: AI Content Generation Policy (parent) +- TRA-OPS-0005: Human Oversight Requirements +- Privacy Policy (to be drafted) + +--- + +## Approval + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| **Policy Owner** | John Stroh | [Pending] | [TBD] | +| **Technical Reviewer** | Claude Code | [Pending] | 2025-10-07 | +| **Final Approval** | John Stroh | [Pending] | [TBD] | + +--- + +**Status**: DRAFT (awaiting John Stroh approval) +**Effective Date**: Upon Phase 2 media inquiry form launch +**Next Review**: 2026-01-07 diff --git a/governance/TRA-OPS-0004-case-study-moderation-standards-v1-0.md b/governance/TRA-OPS-0004-case-study-moderation-standards-v1-0.md new file mode 100644 index 00000000..68992420 --- /dev/null +++ b/governance/TRA-OPS-0004-case-study-moderation-standards-v1-0.md @@ -0,0 +1,419 @@ +# TRA-OPS-0004: Case Study Moderation Standards v1.0 + +**Document ID**: TRA-OPS-0004 +**Version**: 1.0 +**Classification**: OPERATIONAL +**Status**: DRAFT → ACTIVE (upon Phase 2 start) +**Created**: 2025-10-07 +**Owner**: John Stroh +**Review Cycle**: Quarterly +**Next Review**: 2026-01-07 +**Parent Policy**: TRA-OPS-0001 (AI Content Generation Policy) + +--- + +## Purpose + +This document establishes moderation standards for community-submitted case studies of real-world AI failures, ensuring quality, accuracy, and Tractatus framework relevance. + +## Scope + +Applies to all case study submissions via `/submit-case-study`, including: +- AI system failures (production incidents) +- LLM misalignment examples (jailbreaks, hallucinations) +- Governance failures (privacy breaches, bias incidents) +- Speculative scenarios (if well-reasoned) + +--- + +## Submission Requirements + +### Mandatory Fields + +| Field | Description | Example | +|-------|-------------|---------| +| **Title** | Concise incident description (50 chars) | "ChatGPT Medical Advice Hallucination" | +| **Summary** | 2-3 sentence overview (200 chars) | "ChatGPT provided confident but incorrect medical diagnosis..." | +| **Date** | When incident occurred | 2024-03-15 | +| **AI System** | Platform/model involved | ChatGPT (GPT-4) | +| **Source** | URL or citation | https://example.com/article | +| **Failure Mode** | Category (see below) | Hallucination | +| **Description** | Detailed narrative (500-2000 words) | [Full text] | +| **Impact** | Real-world harm or potential | Patient delayed seeking real medical help | +| **Submitter Name** | For attribution | Jane Doe | +| **Submitter Email** | For contact | jane@example.com (not public) | +| **Consent** | Public attribution checkbox | ✓ Checked | + +### Optional Fields + +| Field | Description | +|-------|-------------| +| **Tractatus Analysis** | Submitter's view of which framework boundary was crossed | +| **Prevention Strategy** | How Tractatus could prevent this | +| **Additional Links** | Follow-up articles, discussions | + +--- + +## Failure Mode Categories + +### Taxonomy + +1. **Hallucination**: AI generates false information presented as fact +2. **Boundary Violation**: AI makes values/ethical decision without human approval +3. **Instruction Override**: AI disregards explicit user instructions (27027-type) +4. **Privacy Breach**: AI exposes sensitive data +5. **Bias/Discrimination**: AI exhibits unfair treatment based on protected characteristics +6. **Safety Bypass**: AI provides harmful information despite safety measures +7. **Context Failure**: AI loses track of conversation context, makes incoherent decisions +8. **Ambiguity Exploitation**: AI interprets ambiguous instructions in harmful way + +**AI Role**: Suggest category based on description (human verifies). + +--- + +## AI-Assisted Analysis + +### Step 1: Relevance Assessment + +**AI Task**: Determine if submission is relevant to Tractatus framework. + +**Input to AI**: +```markdown +Analyze this case study submission for Tractatus relevance. + +Title: [TITLE] +Summary: [SUMMARY] +Failure Mode: [CATEGORY] +Description: [FULL_TEXT] + +Tractatus Framework focuses on: +- Architectural constraints (not behavioral alignment) +- Instruction persistence (AI remembers explicit instructions) +- Boundary enforcement (values decisions require humans) +- Context pressure monitoring (detecting degraded operation) + +Question: Is this case study relevant to Tractatus framework? + +Output format: +Relevant: [Yes|No|Maybe] +Confidence: [0.0-1.0] +Reasoning: [3-sentence explanation] +Tractatus Mapping: [Which framework component applies?] +``` + +**Human Override**: Admin can approve "Maybe" cases if insightful. + +--- + +### Step 2: Tractatus Framework Mapping + +**AI Task**: Map incident to Tractatus components. + +**Output Example**: +```json +{ + "relevant": true, + "confidence": 0.88, + "reasoning": "Incident demonstrates instruction override failure (27027-type). User explicitly instructed 'use MongoDB port 27017' but AI changed to 27027 based on pattern-matching. This is directly addressed by CrossReferenceValidator.", + "framework_components": [ + { + "component": "CrossReferenceValidator", + "applies": true, + "explanation": "Would have caught instruction override before execution" + }, + { + "component": "InstructionPersistenceClassifier", + "applies": true, + "explanation": "Would have tagged instruction as HIGH persistence (SYSTEM quadrant)" + } + ], + "prevention_strategy": "CrossReferenceValidator would check proposed action (port 27027) against instruction database (port 27017) and reject before execution." +} +``` + +--- + +### Step 3: Quality Assessment + +**AI Task**: Evaluate submission quality (completeness, clarity, sources). + +**Quality Checklist**: +- [ ] Incident clearly described (who, what, when, where, why) +- [ ] Source provided (URL or citation) +- [ ] Impact explained (actual or potential harm) +- [ ] Failure mode correctly categorized +- [ ] Sufficient detail for analysis (500+ words) +- [ ] No obvious factual errors (AI flags, human verifies) + +**Quality Score**: 0.0-1.0 (threshold: 0.6 for publication) + +--- + +## Human Moderation Workflow + +### Step 1: Submission Received + +**Trigger**: Form submitted at `/submit-case-study` + +**Automated Actions**: +1. Log to database (`case_submissions` collection) +2. Send confirmation email to submitter +3. Alert admin (moderation queue notification) + +**No Auto-Publication**: All submissions require human approval. + +--- + +### Step 2: AI Analysis Queue + +**Status**: "Pending AI Analysis" + +**AI Processing** (asynchronous): +1. Relevance assessment +2. Tractatus mapping +3. Quality evaluation + +**Output**: AI analysis object (stored in database) + +**Status Update**: "Pending Human Review" + +--- + +### Step 3: Human Moderation Dashboard + +**Admin Dashboard**: `/admin/case-studies` + +**UI Elements**: +- Submission list (sorted by submission date) +- AI relevance score (color-coded) +- Quality score (0.0-1.0) +- Quick actions: Approve | Edit | Request Changes | Reject + +**Moderation Criteria**: + +**APPROVE** if: +- ✓ Relevant to Tractatus framework (AI confidence >0.7 OR human override) +- ✓ Quality score >0.6 (or human override for exceptional cases) +- ✓ Source credible (verified by human) +- ✓ No obvious factual errors +- ✓ Submitter consent checkbox checked + +**REQUEST CHANGES** if: +- ⚠ Low quality score (0.4-0.6) but salvageable +- ⚠ Missing source information +- ⚠ Unclear description (needs elaboration) +- ⚠ Wrong category (suggest correct one) + +**REJECT** if: +- ❌ Not relevant to Tractatus (AI confidence <0.3, human agrees) +- ❌ Quality score <0.4 (insufficient detail) +- ❌ Source not credible (blog rumor, no evidence) +- ❌ Obvious factual errors +- ❌ Spam, advertisement, or off-topic +- ❌ No submitter consent + +--- + +### Step 4: Approval Actions + +**If APPROVED**: +1. Status → "Approved" +2. Publish to `/case-studies/[slug]` +3. Add to case study index +4. Email submitter: "Thank you, your case study is now live" +5. Tweet/social share (future) + +**If REQUEST CHANGES**: +1. Status → "Changes Requested" +2. Email submitter with specific feedback +3. Submitter can resubmit via unique edit link + +**If REJECTED**: +1. Status → "Rejected" +2. Email submitter with rejection reason (specific, helpful) +3. Option to revise and resubmit + +--- + +## Moderation Guidelines + +### Factual Accuracy + +**Standard**: All claims must be verifiable. + +**Verification Process**: +1. Check source link (does article exist?) +2. Verify key facts (dates, system names, outcomes) +3. Flag unverified claims for submitter clarification +4. If major discrepancies → Request Changes or Reject + +**AI Assistance**: AI can flag potential errors, but human must verify. + +--- + +### Source Credibility + +**Tier 1 (Highest Credibility)**: +- News outlets (NY Times, Wired, Ars Technica) +- Academic papers (peer-reviewed journals) +- Official incident reports (company postmortems, gov't investigations) +- Technical blogs from verified experts + +**Tier 2 (Acceptable)**: +- Smaller news sites (if facts verifiable) +- Personal blogs from domain experts (if well-cited) +- Social media from verified accounts (archived) + +**Tier 3 (Requires Caution)**: +- Reddit, HackerNews discussions (corroborate with Tier 1/2) +- Anonymous sources (verify claims independently) + +**Unacceptable**: +- No source provided +- Broken links +- Paywalled sources (submitter must provide archived version) + +--- + +### Tractatus Relevance + +**High Relevance** (AI confidence >0.8): +- Direct instruction override (27027-type) +- Boundary violations (AI making values decisions) +- Context pressure failures (AI degrading under load) + +**Medium Relevance** (0.5-0.8): +- Hallucinations (if related to context limits) +- Bias incidents (if boundary enforcement could prevent) +- Safety bypasses (if instruction persistence applies) + +**Low Relevance** (<0.5): +- Generic AI failures unrelated to architecture +- Issues solvable by behavioral alignment only +- Non-LLM AI systems (unless architectural lessons apply) + +**Human Judgment**: Low-relevance submissions may still be approved if they provide valuable contrast ("how Tractatus differs from alignment approaches"). + +--- + +### Tone & Presentation + +**Acceptable**: +- Objective, factual tone +- Critical but fair analysis +- Speculation clearly labeled as such + +**Unacceptable**: +- Sensationalism ("AI gone rogue!") +- Personal attacks on developers/companies +- Fear-mongering without evidence +- Promotional content disguised as case study + +**Editing**: Admin may lightly edit for clarity, grammar, formatting (with note to submitter). + +--- + +## Attribution & Licensing + +### Submitter Attribution + +**Default**: Submitter name + optional link (website, Twitter) + +**Example**: +```markdown +**Submitted by**: Jane Doe ([janedoe.com](https://janedoe.com)) +**Reviewed by**: Tractatus Team +**Published**: 2025-10-15 +``` + +**Anonymous Option**: Submitter can request "Submitted by: Anonymous" (but must still provide email for contact). + +--- + +### Content Licensing + +**License**: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0) + +**Rationale**: Encourages sharing, derivative work, while requiring attribution. + +**Submitter Agreement** (consent checkbox): +> By submitting, I grant the Tractatus Framework project a non-exclusive, worldwide license to publish this case study under CC BY-SA 4.0. I confirm that I am the original author or have permission to submit this content. + +--- + +## Rejection Reasons (Examples) + +**Clear, Specific Feedback**: + +❌ **Too generic**: "Not relevant to Tractatus" → ✅ **Specific**: "This incident relates to training data bias, which Tractatus framework doesn't address (focuses on runtime architectural constraints). Consider reframing to emphasize if boundary enforcement could prevent deployment of biased model." + +❌ **Too harsh**: "This is poorly written" → ✅ **Constructive**: "The description lacks detail about the failure mechanism. Could you expand on how the AI overrode the instruction? What was the exact prompt and response?" + +--- + +## Performance Metrics + +### Moderation Quality + +**Metrics**: +- Approval rate: 50-70% (target - indicates good filter) +- Time to first review: <7 days (target) +- Revision rate: <30% (approved after changes requested) +- Submitter satisfaction: 4+/5 (post-moderation survey) + +### Case Study Engagement + +**Metrics**: +- Views/case: 100+ (soft launch target) +- Social shares: 10+/case +- Community submissions: 3+/month (Phase 2) + +--- + +## Seed Content (Phase 2 Launch) + +**Goal**: Publish 3-5 high-quality case studies before opening community submissions. + +**Curated Examples**: +1. **The 27027 Incident** (canonical example of instruction override) +2. **ChatGPT Medical Hallucination** (boundary violation - health advice without human MD) +3. **GitHub Copilot Code Injection** (context pressure - suggestion based on incomplete understanding) +4. **Bing Chat Sydney Persona** (metacognitive failure - AI loses track of instructions) +5. **Jasper AI Copyright Violation** (boundary violation - legal decision without human lawyer) + +**Author**: John Stroh (or AI-assisted, human-reviewed per TRA-OPS-0002) + +--- + +## Revision & Updates + +**Review Cycle**: Quarterly + +**Update Triggers**: +- Approval rate <40% (standards too strict) or >80% (too lenient) +- User complaints about rejection reasons +- New failure mode categories emerge + +--- + +## Related Documents + +- TRA-OPS-0001: AI Content Generation Policy (parent) +- TRA-OPS-0002: Blog Editorial Guidelines (similar quality standards) +- TRA-OPS-0005: Human Oversight Requirements + +--- + +## Approval + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| **Policy Owner** | John Stroh | [Pending] | [TBD] | +| **Technical Reviewer** | Claude Code | [Pending] | 2025-10-07 | +| **Final Approval** | John Stroh | [Pending] | [TBD] | + +--- + +**Status**: DRAFT (awaiting John Stroh approval) +**Effective Date**: Upon Phase 2 case study portal launch +**Next Review**: 2026-01-07 diff --git a/governance/TRA-OPS-0005-human-oversight-requirements-v1-0.md b/governance/TRA-OPS-0005-human-oversight-requirements-v1-0.md new file mode 100644 index 00000000..c7c81421 --- /dev/null +++ b/governance/TRA-OPS-0005-human-oversight-requirements-v1-0.md @@ -0,0 +1,578 @@ +# TRA-OPS-0005: Human Oversight Requirements v1.0 + +**Document ID**: TRA-OPS-0005 +**Version**: 1.0 +**Classification**: OPERATIONAL +**Status**: DRAFT → ACTIVE (upon Phase 2 start) +**Created**: 2025-10-07 +**Owner**: John Stroh +**Review Cycle**: Quarterly +**Next Review**: 2026-01-07 +**Parent Policy**: TRA-OPS-0001 (AI Content Generation Policy) + +--- + +## Purpose + +This document establishes comprehensive human oversight requirements for all AI-powered features on the Tractatus Framework website, ensuring compliance with the framework's core principle: **"What cannot be systematized must not be automated."** + +## Scope + +Applies to all AI operations requiring human judgment, including: +- Content generation (blogs, responses, analyses) +- Decision-making (publish, respond, approve) +- Values-sensitive operations (editorial policy, external communication) +- System configuration (API limits, moderation rules) + +--- + +## Oversight Principles + +### 1. Mandatory Human Approval (MHA) + +**Definition**: Certain operations MUST have explicit human approval before execution. + +**Applies to**: +- Publishing any public content (blog posts, case studies) +- Sending external communications (media responses, emails) +- Changing editorial policy or moderation rules +- Modifying Tractatus framework governance documents + +**Implementation**: System enforces approval workflow; no bypass mechanism. + +**Tractatus Mapping**: STRATEGIC and some OPERATIONAL quadrants. + +--- + +### 2. Human-in-the-Loop (HITL) + +**Definition**: AI proposes actions; human reviews and decides. + +**Applies to**: +- Blog topic suggestions → Human selects +- Media inquiry classification → Human verifies +- Case study relevance assessment → Human approves +- Draft responses → Human edits before sending + +**Implementation**: Moderation queue with approve/reject/edit workflows. + +**Tractatus Mapping**: OPERATIONAL and TACTICAL quadrants. + +--- + +### 3. Human-on-the-Loop (HOTL) + +**Definition**: AI executes within predefined bounds; human monitors and can intervene. + +**Applies to**: +- Automated logging and metrics +- Database backups +- Performance monitoring +- Error detection + +**Implementation**: Alerting system; human can halt/adjust. + +**Tractatus Mapping**: SYSTEM quadrant (technical operations). + +--- + +### 4. Audit Trail + +**Definition**: All AI decisions and human approvals must be logged for review. + +**Applies to**: All AI operations. + +**Implementation**: Database logging with immutable audit trail. + +**Retention**: 2 years minimum. + +--- + +## Oversight Roles & Responsibilities + +### Admin Reviewer + +**Qualifications**: +- Understands Tractatus framework principles +- Technical background (AI/ML familiarity) +- Editorial judgment (writing, fact-checking) +- Authorized by John Stroh + +**Responsibilities**: +- Review AI-generated content (blogs, drafts, analyses) +- Approve/reject/edit AI proposals +- Monitor moderation queues (daily during Phase 2) +- Escalate ambiguous cases to John Stroh +- Participate in quarterly governance reviews + +**Authority Level**: +- Can approve: Blog posts, media responses (standard), case studies +- Must escalate: Policy changes, major media inquiries, legal issues + +**Training**: TRA-OPS-* document review + hands-on moderation practice. + +--- + +### John Stroh (Owner) + +**Responsibilities**: +- Final authority on all strategic decisions +- Approval for new AI systems/models +- Governance document amendments +- High-priority media inquiries +- Incident response (boundary violations, security) + +**Authority Level**: Unlimited (can override any AI or admin decision). + +--- + +### Future Roles (Phase 3) + +**Editorial Board** (3-5 members): +- Blog content review +- Editorial policy recommendations +- Community engagement oversight + +**Technical Advisory** (2-3 experts): +- Framework architecture review +- AI system evaluation +- Security audit + +--- + +## Oversight Workflows + +### Blog Post Workflow + +```mermaid +graph TD + A[AI Topic Suggestion] -->|Weekly batch| B[Admin Review Queue] + B -->|Approve 1-3 topics| C[AI Outline Generation] + B -->|Reject| Z[End] + C -->|48h| D[Admin Review Outline] + D -->|Approve| E[Human Writes Draft] + D -->|Reject| Z + E --> F[Admin Final Approval] + F -->|Approve| G[Publish] + F -->|Edit| E + F -->|Reject| Z +``` + +**Oversight Points**: +1. **Topic Selection**: Admin decides (STRATEGIC - editorial direction) +2. **Outline Review**: Admin verifies (OPERATIONAL - quality control) +3. **Final Approval**: Admin decides to publish (STRATEGIC - external communication) + +**SLA**: +- Topic review: 7 days (weekly) +- Outline review: 48 hours +- Final approval: 24 hours before scheduled publish + +**Escalation**: +- Controversial topics → John Stroh approval required +- Technical deep dives → No escalation (admin discretion) + +--- + +### Media Inquiry Workflow + +```mermaid +graph TD + A[Inquiry Received] --> B[AI Classification & Triage] + B -->|4h for HIGH priority| C[Admin Review Dashboard] + C -->|Approve Draft| D[Send Response] + C -->|Edit Draft| E[Admin Edits] + C -->|Escalate| F[John Stroh Decision] + C -->|Ignore| Z[Archive] + E --> D + F --> D + F --> Z +``` + +**Oversight Points**: +1. **Classification Review**: Admin verifies AI categorization (OPERATIONAL) +2. **Send Decision**: Admin decides whether to respond (STRATEGIC - external relations) +3. **Escalation**: High-priority or ambiguous → John Stroh (STRATEGIC) + +**SLA**: +- HIGH priority: 4 hours (business days) +- MEDIUM priority: 48 hours +- LOW priority: 7 days + +**Escalation Triggers**: +- Major media (NY Times, Wired, etc.) +- Government/regulatory +- Legal issues +- Controversy/criticism + +--- + +### Case Study Workflow + +```mermaid +graph TD + A[Community Submission] --> B[AI Relevance Analysis] + B -->|7 days| C[Admin Moderation Queue] + C -->|Approve| D[Publish to Portal] + C -->|Request Changes| E[Email Submitter] + C -->|Reject with Reason| F[Email Submitter] + E -->|Resubmit| A +``` + +**Oversight Points**: +1. **Relevance Verification**: Admin checks AI analysis (OPERATIONAL) +2. **Publication Decision**: Admin decides to publish (STRATEGIC - public content) + +**SLA**: 7 days from submission to decision + +**Escalation**: None (admin discretion unless policy question arises) + +--- + +## Service Level Agreements (SLAs) + +### Response Times + +| Task | SLA | Escalation (if missed) | +|------|-----|------------------------| +| **HIGH priority media inquiry** | 4 hours | Alert John Stroh | +| **Blog outline review** | 48 hours | Notify admin (reminder) | +| **Blog final approval** | 24 hours | Delay publication | +| **Case study moderation** | 7 days | Notify submitter (apology + timeline) | +| **MEDIUM media inquiry** | 48 hours | Standard workflow (no escalation) | +| **LOW media inquiry** | 7 days | Best-effort (no penalty) | + +### Workload Expectations + +**Admin Reviewer** (Phase 2 - Soft Launch): +- Time commitment: 5-10 hours/week +- Tasks/week: + - Blog topics: 1 review session (1 hour) + - Blog drafts: 2-4 approvals (2-4 hours) + - Media inquiries: 5-10 reviews (2-3 hours) + - Case studies: 3-5 reviews (1-2 hours) + +**Peak Load** (Phase 3 - Public Launch): +- Time commitment: 15-20 hours/week +- Consider additional admin reviewers + +--- + +## Approval Authority Matrix + +| Decision Type | Admin Reviewer | John Stroh | Notes | +|---------------|----------------|------------|-------| +| **Blog Post (Standard)** | ✓ Approve | Override | Admin sufficient | +| **Blog Post (Controversial)** | Recommend | ✓ Approve | Must escalate | +| **Media Response (Standard)** | ✓ Approve | Override | Admin sufficient | +| **Media Response (Major Outlet)** | Recommend | ✓ Approve | Must escalate | +| **Case Study (Standard)** | ✓ Approve | Override | Admin sufficient | +| **Policy Amendment** | Recommend | ✓ Approve | Always escalate | +| **AI System Change** | Recommend | ✓ Approve | Always escalate | +| **Emergency Response** | Recommend | ✓ Approve | Security/legal incidents | + +--- + +## Quality Assurance + +### AI Output Quality Checks + +**Before Approval**, admin must verify: + +**Factual Accuracy**: +- [ ] All citations exist and are correct (no hallucinations) +- [ ] Dates, names, technical details verified +- [ ] No obvious errors (grammar, logic, coherence) + +**Alignment**: +- [ ] Content aligns with Tractatus framework principles +- [ ] Tone appropriate for audience (professional, accessible) +- [ ] No values decisions made by AI (boundary check) + +**Completeness**: +- [ ] All required sections present (title, summary, body, citations) +- [ ] Sufficient detail (not superficial) +- [ ] Call to action or next steps (if applicable) + +**Legal/Ethical**: +- [ ] No copyright violations (plagiarism check) +- [ ] No privacy violations (PII exposed) +- [ ] No defamation or personal attacks + +--- + +### Rejection Criteria + +**Must reject if**: +- Factual errors that cannot be easily corrected +- Plagiarism or copyright violation +- Values decision made by AI without justification +- Inappropriate tone (offensive, discriminatory) +- Insufficient quality (major rewrite needed) + +**Should request changes if**: +- Minor factual errors (fixable) +- Tone slightly off (needs editing) +- Incomplete (needs expansion) +- Poor formatting (needs cleanup) + +--- + +## Escalation Procedures + +### When to Escalate to John Stroh + +**Mandatory Escalation**: +- Boundary violation detected (AI made values decision without approval) +- Major media inquiry (NY Times, Wired, government) +- Legal threat or security incident +- Policy change request +- New AI system evaluation +- Ambiguous case (unclear if should approve) + +**Escalation Process**: +1. Admin marks item "Escalation Required" in dashboard +2. System emails John Stroh with: + - Context (original request, AI output, admin notes) + - Recommendation (approve, reject, edit) + - Urgency (immediate, 24h, 7 days) +3. John Stroh responds: + - Decision (approve, reject, provide guidance) + - Feedback (for future similar cases) + +**SLA**: John Stroh responds within 24h (for URGENT), 7 days (standard). + +--- + +## Monitoring & Metrics + +### Dashboard Metrics (Admin View) + +**Real-Time**: +- Pending approvals (count by type) +- SLA compliance (% within target) +- Queue age (oldest item waiting) + +**Weekly**: +- Approvals/rejections by category +- Average review time +- AI accuracy (classification, relevance) + +**Monthly**: +- Total content published (blogs, case studies) +- Media inquiries handled +- Escalations to John Stroh + +--- + +### Performance Indicators + +| Metric | Target | Action if Missed | +|--------|--------|------------------| +| **SLA Compliance** | 95% | Increase admin capacity | +| **AI Approval Rate** | 70-90% | Adjust AI prompts if too high/low | +| **Average Review Time** | <24h | Process optimization | +| **Escalation Rate** | <10% | Improve admin training | +| **User Satisfaction** | 4+/5 | Review rejection feedback | + +--- + +## Training & Onboarding + +### Admin Reviewer Onboarding + +**Week 1**: Policy Review +- Read TRA-OPS-0001 through TRA-OPS-0005 +- Review Tractatus framework documentation +- Understand quadrant classification (STR/OPS/TAC/SYS/STO) + +**Week 2**: Hands-On Practice +- Shadow existing admin reviewer (if available) +- Review 5-10 sample cases (pre-approved examples) +- Practice with test submissions + +**Week 3**: Supervised Moderation +- Review real submissions (with John Stroh oversight) +- Receive feedback on decisions +- Identify edge cases + +**Week 4**: Independent Authorization +- Authorized for standard approvals +- John Stroh spot-checks 10% of decisions +- Full authorization after 30 days error-free + +--- + +### Ongoing Training + +**Quarterly**: +- Policy updates review +- Case study retrospective (what went well, what didn't) +- AI accuracy analysis (where did AI fail? improve prompts) + +**Annual**: +- Full governance document review +- External training (AI safety, editorial standards, legal compliance) + +--- + +## Audit & Compliance + +### Internal Audit (Quarterly) + +**Review Sample**: +- 10% of approved content (random selection) +- 100% of rejected content (check for false negatives) +- All escalated cases + +**Audit Criteria**: +- Were approval criteria followed? +- Was SLA met? +- Was AI output quality acceptable? +- Were boundaries respected (no values violations)? + +**Findings**: Document gaps, recommend process improvements. + +--- + +### External Audit (Annual - Phase 3+) + +**Scope**: +- Governance compliance (Tractatus framework) +- Data privacy (GDPR-lite) +- Security (API key handling, PII protection) + +**Auditor**: Independent third party (TBD) + +--- + +## Incident Response + +### Boundary Violation Incident + +**Definition**: AI makes values decision without human approval (e.g., auto-publishes content, sends media response). + +**Response Protocol**: +1. **Immediate** (within 1 hour): + - Halt all AI operations (emergency shutdown) + - Alert John Stroh + - Document incident (what, when, why) + +2. **Within 24 hours**: + - Root cause analysis (how did boundary check fail?) + - Rollback any published content (if applicable) + - Public disclosure (if external impact) + +3. **Within 7 days**: + - Fix implemented (code, process, or both) + - BoundaryEnforcer audit (test all boundary checks) + - Policy review (update TRA-OPS-* if needed) + +4. **Within 30 days**: + - Post-mortem published (transparency) + - Training updated (prevent recurrence) + - Compensation/apology (if harm occurred) + +**Severity Levels**: +- **CRITICAL**: Public harm (incorrect medical advice published, privacy breach) +- **HIGH**: Internal-only (test post published, draft sent to wrong email) +- **MEDIUM**: Near-miss (caught before publication, but boundary check failed) + +--- + +### Poor Quality Content Incident + +**Definition**: Approved content contains factual error or inappropriate tone. + +**Response Protocol**: +1. **Immediate** (within 4 hours): + - Retract or correct content + - Publish correction notice (if public) + +2. **Within 24 hours**: + - Notify submitter/stakeholders + - Root cause analysis (admin missed error? AI hallucination?) + +3. **Within 7 days**: + - Update review checklist (add missed criteria) + - Admin training (if review failure) + - AI prompt improvement (if hallucination) + +--- + +## Cost Management + +### Budget Allocation + +**Phase 2 Budget**: $200/month (Claude API) + +**Allocation**: +- Blog curation: $75/month (30-40% of budget) +- Media triage: $50/month (25% of budget) +- Case study analysis: $50/month (25% of budget) +- Miscellaneous: $25/month (10% buffer) + +**Monitoring**: +- Daily token usage dashboard +- Alert at 80% of monthly budget +- Hard cap at 100% (AI operations paused) + +**Admin Responsibility**: Monitor spend, adjust usage if approaching cap. + +--- + +### Cost Optimization + +**Strategies**: +- Cache AI responses (30-day TTL for identical queries) +- Batch similar requests (weekly topic suggestions, not daily) +- Use Claude Haiku for simple tasks (media classification - 5x cheaper) +- Rate limit users (prevent abuse) + +**Review**: Quarterly cost-benefit analysis (is AI worth the expense?). + +--- + +## Revision & Updates + +### Update Process + +**Minor Updates** (v1.0 → v1.1): +- Clarifications, typo fixes, SLA adjustments +- Approval: Admin reviewer +- Notification: Email to John Stroh + +**Major Updates** (v1.0 → v2.0): +- New oversight roles, workflow changes, authority matrix updates +- Approval: John Stroh +- Notification: Public blog post + +**Emergency Updates**: +- Security/privacy issues requiring immediate change +- Approval: John Stroh (verbal, documented within 24h) + +--- + +## Related Documents + +- TRA-OPS-0001: AI Content Generation Policy (parent) +- TRA-OPS-0002: Blog Editorial Guidelines +- TRA-OPS-0003: Media Inquiry Response Protocol +- TRA-OPS-0004: Case Study Moderation Standards +- STR-GOV-0001: Strategic Review Protocol (sydigital source) + +--- + +## Approval + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| **Policy Owner** | John Stroh | [Pending] | [TBD] | +| **Technical Reviewer** | Claude Code | [Pending] | 2025-10-07 | +| **Final Approval** | John Stroh | [Pending] | [TBD] | + +--- + +**Status**: DRAFT (awaiting John Stroh approval) +**Effective Date**: Upon Phase 2 deployment +**Next Review**: 2026-01-07 (3 months post-activation)