tractatus/docs/BLOG_CURATION_WORKFLOW.md

# Blog Curation Workflow Documentation

**Feature**: AI-Assisted Blog Content Generation with Human Oversight
**Policy**: TRA-OPS-0002 (AI suggests, human decides)
**Tractatus Enforcement**: inst_016, inst_017, inst_018
**Status**: Phase 4 - Production Ready

---

## Table of Contents

1. [Overview](#overview)
2. [Workflow](#workflow)
3. [Tractatus Framework Enforcement](#tractatus-framework-enforcement)
4. [Using the Admin UI](#using-the-admin-ui)
5. [API Endpoints](#api-endpoints)
6. [Troubleshooting](#troubleshooting)

---

## Overview

The Blog Curation system enables AI-assisted content generation while maintaining strict human oversight and Tractatus framework compliance. All AI-generated content undergoes mandatory validation against ethical principles before publication.

### Key Principles

1. **AI Suggests, Human Decides** (TRA-OPS-0002)
   - AI generates draft content and suggestions
   - All content requires human review and approval
   - No automated publication without human oversight

2. **Tractatus Enforcement**
   - **inst_016**: Never fabricate statistics or make unverifiable claims
   - **inst_017**: Never use absolute assurance terms (guarantee, 100%, never fails)
   - **inst_018**: Never claim production-ready status without evidence

3. **Editorial Quality**
   - Evidence-based, transparent, honest content
   - Professional tone, clear structure
   - Cites sources for all claims and statistics

---

## Workflow

### High-Level Flow

```
┌─────────────────┐
│  Admin Requests │
│   Blog Draft    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Boundary Check │ ◄── TRA-OPS-0002
│  (BoundaryEnforcer)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Generate Draft  │
│  (Claude API)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Validate     │ ◄── inst_016, inst_017, inst_018
│  (Tractatus)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Queue for      │
│ Human Review    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Human Reviews  │
│ Approve/Reject  │
└────────┬────────┘
         │
         ▼
    [Publish]
```

### Detailed Steps

#### 1. Draft Generation

**Actor**: Admin user
**Location**: `/admin/blog-curation.html`

1. Admin fills out draft request form:
   - **Topic**: Blog post topic (required)
   - **Audience**: researcher/implementer/advocate/general (required)
   - **Length**: short/medium/long (default: medium)
   - **Focus**: Optional specific angle or focus area

2. System performs boundary check:
   - Validates that content generation is within operational boundaries
   - Confirms human oversight requirement
   - Logs governance action

3. Claude API generates draft:
   - Receives editorial guidelines and Tractatus constraints
   - Generates structured blog post (title, subtitle, content, excerpt, tags, sources)
   - Returns JSON-formatted draft

4. System validates draft:
   - Checks for absolute guarantee terms (inst_017)
   - Verifies statistics have sources (inst_016)
   - Flags unverified production claims (inst_018)
   - Generates validation report

5. Draft queued for review:
   - Creates moderation queue entry
   - Priority: HIGH if violations detected, MEDIUM otherwise
   - Status: PENDING_APPROVAL
   - Includes: draft, validation results, metadata

#### 2. Human Review

**Actor**: Admin user
**Location**: `/admin/blog-curation.html` (Review Queue tab)

1. Admin views pending drafts:
   - Sorted by priority (HIGH violations first)
   - Shows: title, audience, creation date, violation count

2. Admin opens draft for review:
   - Full content preview
   - Validation results (violations, warnings, strengths)
   - Governance policy information
   - Source citations

3. Admin takes action:
   - **Approve**: Create blog post from draft
   - **Reject**: Decline draft, provide reason
   - **Edit**: Modify content before approval (future feature)

4. System processes decision:
   - Logs governance decision
   - Updates moderation queue status
   - If approved: Creates blog post in database
   - If rejected: Archives with reason

#### 3. Publication

**Actor**: Admin user
**Location**: Blog management interface

Once approved, draft becomes editable blog post:
- Status: draft
- Can be further edited by admin
- Published when admin manually sets status to "published"
- Final publication requires explicit admin action

---

## Tractatus Framework Enforcement

### Automated Validation

The system automatically validates all AI-generated content against three core instructions:

#### inst_016: No Fabricated Statistics

**Rule**: Never fabricate statistics or make unverifiable claims

**Detection**:
- Scans content for percentage patterns (`\d+(\.\d+)?%`)
- Checks if sources array is populated
- Warns if statistics found without citations

**Example Violations**:
```
❌ "85% of organizations use our framework"  # No source cited
❌ "Studies show 90% improvement"            # Vague, unverifiable

✅ "According to [Source], 85% of surveyed organizations..."
✅ "Our 2024 user survey (N=500) found 90% improvement..."
```

#### inst_017: No Absolute Guarantees

**Rule**: Never use absolute assurance terms

**Forbidden Terms**:
- guarantee / guaranteed / guarantees
- ensures 100%
- never fails
- always works
- 100% safe / 100% secure

**Detection**:
- Case-insensitive scan for forbidden terms
- Flags violations with HIGH severity
- Blocks publication if detected

**Example Violations**:
```
❌ "Our framework guarantees 100% safety"
❌ "This approach ensures perfect compliance"
❌ "The system never fails to detect issues"

✅ "Our framework aims to improve safety"
✅ "This approach helps enhance compliance"
✅ "The system detects most common issues"
```

#### inst_018: No Unverified Production Claims

**Rule**: Never claim production-ready status without evidence

**Flagged Terms** (require citations):
- battle-tested
- production-proven
- industry-standard

**Detection**:
- Flags terms if no sources provided
- Warns (doesn't block) to allow citation addition

**Example Issues**:
```
⚠️  "Our battle-tested framework..."     # Needs evidence
⚠️  "The industry-standard approach..."  # Needs adoption metrics

✅ "Used in production by 12 organizations (see: [Source])"
✅ "Adopted by industry leaders including [Company A, Company B]"
```

### Validation Recommendations

The validation system provides three recommendations:

| Recommendation | Meaning | Admin Action |
|----------------|---------|--------------|
| **APPROVED** | No violations or warnings | Safe to approve |
| **REVIEW_REQUIRED** | Warnings present, no violations | Review warnings, approve if acceptable |
| **REJECT** | Violations detected | Must reject or edit to fix violations |

---

## Using the Admin UI

### Accessing Blog Curation

1. Navigate to: `https://agenticgovernance.digital/admin/blog-curation.html`
2. Login with admin credentials
3. Three main tabs available:
   - **Draft Content**: Generate new blog posts
   - **Review Queue**: Review pending drafts
   - **Guidelines**: View editorial standards

### Generating a Draft

**Steps**:

1. Go to "Draft Content" tab
2. Fill out the form:
   ```
   Topic:    "Understanding AI Boundary Enforcement in Production Systems"
   Audience: Implementers
   Length:   Medium (1000-1500 words)
   Focus:    "Real-world implementation challenges" (optional)
   ```
3. Click "Generate Draft"
4. Wait for AI generation (typically 10-30 seconds)
5. Review preview modal:
   - Check for Tractatus violations (red alerts)
   - Review warnings (yellow alerts)
   - Examine sources and citations
6. Click "View in Queue" to see in review queue

### Reviewing Drafts

**Steps**:

1. Go to "Review Queue" tab
2. See list of pending drafts:
   - HIGH priority (violations) shown first
   - Shows title, audience, creation date
   - Violation count badge
3. Click "Review" on a draft
4. Review modal opens:
   - Full content displayed
   - Markdown rendered to HTML
   - Violations highlighted
5. Take action:
   - **Approve**: Creates blog post in draft status
   - **Reject**: Archives with rejection reason
   - **Close**: Return to queue for later review

### Editorial Guidelines

**Reference**:

View in "Guidelines" tab for quick reference:

- **Writing Standards**: Tone, voice, style
- **Core Principles**: Transparency, honesty, evidence
- **Forbidden Patterns**: What to avoid
- **Target Word Counts**: Length guidelines

---

## API Endpoints

### POST `/api/blog/draft-post`

Generate AI blog post draft.

**Authentication**: Required (admin role)

**Request Body**:
```json
{
  "topic": "Understanding AI Safety Frameworks",
  "audience": "researcher",
  "length": "medium",
  "focus": "comparative analysis" // optional
}
```

**Response** (200 OK):
```json
{
  "success": true,
  "message": "Blog post draft generated. Awaiting human review and approval.",
  "queue_id": "68e3a7fb21af2fd194bf4c87",
  "draft": {
    "title": "Understanding AI Safety Frameworks: A Comparative Analysis",
    "subtitle": "Examining governance approaches in modern AI systems",
    "content": "# Introduction\n\n...",
    "excerpt": "This article explores...",
    "tags": ["AI safety", "Governance", "Frameworks"],
    "tractatus_angle": "Demonstrates sovereignty principle...",
    "sources": ["https://example.com/research"],
    "word_count": 1250
  },
  "validation": {
    "valid": true,
    "violations": [],
    "warnings": [],
    "stats_found": 3,
    "sources_provided": 1,
    "recommendation": "APPROVED"
  },
  "governance": {
    "policy": "TRA-OPS-0002",
    "boundary_check": { ... },
    "requires_approval": true,
    "tractatus_enforcement": {
      "inst_016": "No fabricated statistics or unverifiable claims",
      "inst_017": "No absolute assurance terms (guarantee, 100%, etc.)",
      "inst_018": "No unverified production-ready claims"
    }
  }
}
```

**Error Response** (403 Forbidden):
```json
{
  "error": "Boundary Violation",
  "message": "This action crosses into values territory requiring human judgment"
}
```

### POST `/api/blog/analyze-content`

Analyze existing content for Tractatus compliance.

**Authentication**: Required (admin role)

**Request Body**:
```json
{
  "title": "My Blog Post Title",
  "body": "Full blog post content here..."
}
```

**Response** (200 OK):
```json
{
  "success": true,
  "analysis": {
    "compliant": false,
    "violations": [
      {
        "type": "ABSOLUTE_CLAIM",
        "severity": "HIGH",
        "excerpt": "guarantees 100% safety",
        "reasoning": "Violates inst_017 - absolute assurance term",
        "suggested_fix": "Replace with 'aims to improve safety' or similar qualified language"
      }
    ],
    "warnings": [ ... ],
    "strengths": [ "Evidence-based", "Cites sources" ],
    "overall_score": 75,
    "recommendation": "EDIT_REQUIRED"
  },
  "tractatus_enforcement": { ... }
}
```

### GET `/api/blog/editorial-guidelines`

Retrieve editorial guidelines.

**Authentication**: Required (admin or moderator role)

**Response** (200 OK):
```json
{
  "success": true,
  "guidelines": {
    "tone": "Professional, informative, evidence-based",
    "voice": "Third-person objective (AI safety framework documentation)",
    "style": "Clear, accessible technical writing",
    "principles": [ ... ],
    "forbiddenPatterns": [ ... ],
    "targetWordCounts": {
      "short": "600-900 words",
      "medium": "1000-1500 words",
      "long": "1800-2500 words"
    }
  }
}
```

### GET `/api/admin/moderation-queue?type=BLOG_POST_DRAFT`

Retrieve pending blog drafts from moderation queue.

**Authentication**: Required (admin or moderator role)

**Response** (200 OK):
```json
{
  "success": true,
  "queue": [
    {
      "_id": "68e3a7fb21af2fd194bf4c87",
      "type": "BLOG_POST_DRAFT",
      "status": "pending",
      "priority": "high",
      "created_at": "2025-10-10T12:00:00Z",
      "data": {
        "topic": "...",
        "audience": "...",
        "draft": { ... },
        "validation": { ... }
      }
    }
  ],
  "pagination": { ... }
}
```

---

## Troubleshooting

### Common Issues

#### Issue: "Claude API key not configured"

**Cause**: `CLAUDE_API_KEY` environment variable not set

**Solution**:
```bash
# Development
export CLAUDE_API_KEY="sk-ant-api03-..."

# Production
# Set in environment variables or .env file (not committed to git)
```

#### Issue: Draft generation times out

**Cause**: Claude API slow response or network issues

**Solution**:
- Check network connectivity
- Verify Claude API status
- Try shorter length ("short" instead of "long")
- Check API rate limits

#### Issue: All drafts show HIGH violations

**Cause**: AI generating content with forbidden patterns

**Solution**:
- Review editorial guidelines
- Check if system prompt is being sent correctly
- Verify inst_016/017/018 are in system prompt
- May need to adjust temperature (currently 0.7)

#### Issue: Moderation queue not loading

**Cause**: MongoDB connection or authentication issues

**Solution**:
```bash
# Check MongoDB connection
mongosh tractatus_dev --eval "db.adminCommand('ping')"

# Check moderation queue collection
mongosh tractatus_dev --eval "db.moderation_queue.countDocuments({ type: 'BLOG_POST_DRAFT' })"

# Verify authentication token
# Check browser console for 401 errors
```

#### Issue: Tests failing with mock errors

**Cause**: Jest mocking not properly configured

**Solution**:
```bash
# Update test file to properly mock dependencies
# See: tests/unit/BlogCuration.service.test.js

# Mock should be set up before require:
jest.mock('../../src/services/ClaudeAPI.service', () => ({
  sendMessage: jest.fn(),
  extractJSON: jest.fn()
}));
```

### Debugging

**Enable detailed logging**:
```javascript
// In BlogCuration.service.js
logger.setLevel('debug');
```

**Check governance logs**:
```bash
mongosh tractatus_dev --eval "
  db.governance_logs.find({
    action: 'BLOG_POST_DRAFT'
  }).sort({ timestamp: -1 }).limit(10)
"
```

**View moderation queue entries**:
```bash
mongosh tractatus_dev --eval "
  db.moderation_queue.find({
    type: 'BLOG_POST_DRAFT'
  }).pretty()
"
```

---

## Quick Reference: Manual Blog Publishing (via mongosh)

When you have a finished blog post and want to publish it directly (bypassing the AI curation pipeline), use this method. This is the proven approach — used successfully on 2026-02-08.

### Prerequisites

- SSH access: `ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net`
- Production database: `mongodb://localhost:27017/tractatus`
- Collection: `blog_posts`
- Production app path: `/var/www/tractatus/`

### Step 1: Create a mongosh insert script

Create a local file (e.g., `/tmp/insert-blog-post.js`) with this structure:

```javascript
// /tmp/insert-blog-post.js
db = db.getSiblingDB('tractatus');

db.blog_posts.insertOne({
  title: "Your Blog Post Title",
  slug: "your-blog-post-title-slugified",
  subtitle: "Optional subtitle",
  author: "Author Name",
  content: `<p>Your HTML content here.</p>
<h2>Section Heading</h2>
<p>More content...</p>`,
  excerpt: "A short summary for the blog listing page.",
  tags: ["tag1", "tag2", "tag3"],
  status: "published",
  featured: false,
  publishedAt: new Date(),
  createdAt: new Date(),
  updatedAt: new Date()
});

print("Blog post inserted successfully");
print("URL: https://agenticgovernance.digital/blog-post.html?slug=your-blog-post-title-slugified");
```

**Important**: Content must be HTML (not markdown). The blog renders content via `innerHTML`.

### Step 2: Upload and execute on production

```bash
# Upload the script
scp -i ~/.ssh/tractatus_deploy /tmp/insert-blog-post.js \
  ubuntu@vps-93a693da.vps.ovh.net:/tmp/insert-blog-post.js

# Execute it
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net \
  "mongosh --quiet mongodb://localhost:27017/tractatus /tmp/insert-blog-post.js"

# Clean up
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net \
  "rm /tmp/insert-blog-post.js"
```

### Step 3: Verify

```bash
# Check via API
curl -s "https://agenticgovernance.digital/api/blog/your-slug-here" | python3 -m json.tool | head -5

# View in browser
# https://agenticgovernance.digital/blog-post.html?slug=your-slug-here
# Also listed on: https://agenticgovernance.digital/blog.html
```

### Blog post schema fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `title` | String | Yes | Display title |
| `slug` | String | Yes | URL-safe, lowercase, hyphens. Must be unique |
| `subtitle` | String | No | Shown below title |
| `author` | String | Yes | Author name |
| `content` | String | Yes | **HTML** (not markdown) |
| `excerpt` | String | Yes | Short summary for listing page |
| `tags` | Array | No | String array for categorization |
| `status` | String | Yes | `"published"` or `"draft"` |
| `featured` | Boolean | No | Highlights on blog listing |
| `publishedAt` | Date | Yes | Publication timestamp |
| `createdAt` | Date | Yes | Creation timestamp |
| `updatedAt` | Date | Yes | Last update timestamp |

### Deploying frontend changes (navbar, blog page, etc.)

The Tractatus deploy script handles cache busting and rsync:

```bash
cd ~/projects/tractatus

# Frontend only (public/ directory)
./scripts/deploy.sh --frontend-only --yes

# Single file (manual scp)
scp -i ~/.ssh/tractatus_deploy public/js/components/navbar.js \
  ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/public/js/components/navbar.js
```

**Production paths**: App root is `/var/www/tractatus/` (NOT `/home/ubuntu/tractatus/`). The `/home/ubuntu/tractatus/` directory only contains a `scripts/` folder.

---

## Next Steps

### Future Enhancements

1. **Edit Before Approval**: Allow admins to edit drafts before approval
2. **Batch Operations**: Approve/reject multiple drafts at once
3. **Draft Templates**: Pre-defined templates for common blog types
4. **Multi-language Support**: Generate drafts in multiple languages
5. **SEO Optimization**: Automated SEO suggestions
6. **Image Generation**: AI-suggested featured images
7. **Scheduled Publishing**: Queue approved posts for future publication

### Monitoring

**Metrics to track**:
- Draft generation success rate
- Average validation score
- Violation frequency by type
- Human approval rate
- Time from draft to publication

**Alerts to configure**:
- High violation frequency (>50% of drafts)
- Draft generation failures
- Queue backlog (>10 pending drafts)
- API errors or timeouts

---

## Reference Documents

- **Tractatus Framework**: `CLAUDE_Tractatus_Maintenance_Guide.md`
- **Framework Enforcement**: `docs/claude-code-framework-enforcement.md`
- **Instruction History**: `.claude/instruction-history.json`
- **API Documentation**: See controller files in `src/controllers/blog.controller.js`

---

**Last Updated**: 2025-10-10
**Version**: 1.0.0
**Status**: Production Ready

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>