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
2. Workflow
3. Tractatus Framework Enforcement
4. Using the Admin UI
5. API Endpoints
6. 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:

{
  "topic": "Understanding AI Safety Frameworks",
  "audience": "researcher",
  "length": "medium",
  "focus": "comparative analysis" // optional
}

Response (200 OK):

{
  "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):

{
  "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:

{
  "title": "My Blog Post Title",
  "body": "Full blog post content here..."
}

Response (200 OK):

{
  "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):

{
  "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):

{
  "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:

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

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

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

// In BlogCuration.service.js
logger.setLevel('debug');

Check governance logs:

mongosh tractatus_dev --eval "
  db.governance_logs.find({
    action: 'BLOG_POST_DRAFT'
  }).sort({ timestamp: -1 }).limit(10)
"

View moderation queue entries:

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:

// /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

# 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

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

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

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