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()
"

---

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