diff --git a/docs/markdown/implementation-guide-v1.1.md b/docs/markdown/implementation-guide-v1.1.md new file mode 100644 index 00000000..85f68167 --- /dev/null +++ b/docs/markdown/implementation-guide-v1.1.md @@ -0,0 +1,544 @@ +# Tractatus Framework Implementation Guide + +**Version**: 1.1 +**Last Updated**: 2025-10-11 +**Status**: Production-Ready (Phase 5 Complete) + +--- + +## Overview + +This guide covers production deployment of the Tractatus Agentic Governance Framework with MongoDB persistence and optional API Memory integration. + +**Architecture**: Hybrid memory system +- **MongoDB** (required): Persistent storage for governance rules, audit logs +- **Anthropic API Memory** (optional): Session continuity enhancement +- **Filesystem** (debug): Audit trail for development + +See the **Architectural Overview** document for complete system architecture and research status. + +--- + +## Prerequisites + +### Required + +- **Node.js**: v18+ LTS +- **MongoDB**: v7.0+ +- **npm** or **yarn**: Latest stable +- **Git**: For cloning repository + +### Optional + +- **Anthropic API Key**: For API Memory features +- **systemd**: For production process management (Linux) + +--- + +## Installation + +### 1. Clone Repository + +```bash +git clone https://github.com/AgenticGovernance/tractatus.git +cd tractatus +``` + +### 2. Install Dependencies + +```bash +npm install +``` + +**Key Dependencies**: +- `mongodb`: v8.x (MongoDB driver) +- `mongoose`: v8.x (ODM for models) +- `express`: v4.x (Web framework) +- `marked`: v14.x (Markdown processing) +- `@anthropic-ai/sdk`: v0.65+ (API Memory - optional) + +### 3. MongoDB Setup + +**Option A: Local Development** + +```bash +# Install MongoDB (Ubuntu/Debian) +sudo apt-get install mongodb-org + +# Start MongoDB +sudo systemctl start mongod +sudo systemctl enable mongod + +# Create database +mongosh +> use tractatus_dev +> db.createCollection('governanceRules') +> db.createCollection('auditLogs') +> db.createCollection('documents') +> exit +``` + +**Option B: MongoDB Atlas (Cloud)** + +1. Create free cluster at https://mongodb.com/atlas +2. Add IP whitelist: `0.0.0.0/0` (development) or specific IPs (production) +3. Create database user with read/write permissions +4. Get connection string: `mongodb+srv://user:pass@cluster.mongodb.net/tractatus` + +### 4. Environment Configuration + +Create `.env` file in project root: + +```bash +# Required +MONGODB_URI=mongodb://localhost:27017/tractatus_dev +MONGODB_DB=tractatus_dev +NODE_ENV=development +PORT=9000 + +# Optional - API Memory Features +CLAUDE_API_KEY=your_anthropic_api_key_here + +# Optional - JWT for admin features +JWT_SECRET=your_random_secret_here_minimum_32_characters +``` + +**Security Notes**: +- Never commit `.env` to version control +- Use strong JWT secrets in production (32+ characters) +- Restrict MongoDB access by IP in production + +--- + +## Framework Initialization + +### Service Architecture + +The framework consists of 6 core services: + +1. **InstructionPersistenceClassifier**: Classify and persist user instructions +2. **CrossReferenceValidator**: Validate actions against stored instructions +3. **BoundaryEnforcer**: Enforce inst_016-018 content validation +4. **ContextPressureMonitor**: Monitor session quality degradation +5. **MetacognitiveVerifier**: Confidence-based action verification +6. **BlogCuration**: Validate blog content against governance rules + +All services integrate with **MemoryProxy** for MongoDB access. + +### Basic Initialization + +```javascript +const InstructionPersistenceClassifier = require('./src/services/InstructionPersistenceClassifier.service'); +const CrossReferenceValidator = require('./src/services/CrossReferenceValidator.service'); +const BoundaryEnforcer = require('./src/services/BoundaryEnforcer.service'); +const ContextPressureMonitor = require('./src/services/ContextPressureMonitor.service'); +const MetacognitiveVerifier = require('./src/services/MetacognitiveVerifier.service'); +const BlogCuration = require('./src/services/BlogCuration.service'); + +// Initialize all services (loads governance rules from MongoDB) +async function initializeFramework() { + await InstructionPersistenceClassifier.initialize(); + await CrossReferenceValidator.initialize(); + await BoundaryEnforcer.initialize(); + await ContextPressureMonitor.initialize(); + await MetacognitiveVerifier.initialize(); + await BlogCuration.initialize(); + + console.log('✓ Tractatus Framework initialized'); +} + +// Call during application startup +initializeFramework(); +``` + +### Service Usage Examples + +#### 1. Classify User Instructions + +```javascript +const classification = InstructionPersistenceClassifier.classify({ + text: "Always use MongoDB port 27017 for this project", + context: { + conversation_tokens: 5000, + conversation_length: 20 + } +}); + +console.log(classification); +// { +// quadrant: 'SYSTEM', +// persistence: 'HIGH', +// temporalScope: 'PERMANENT', +// verificationRequired: 'MANDATORY', +// parameters: { port: 27017, database: 'mongodb' } +// } +``` + +#### 2. Validate Actions + +```javascript +const validation = await CrossReferenceValidator.validate( + "Change MongoDB port to 27018", + { explicit_instructions: await loadInstructions() } +); + +if (validation.status === 'REJECTED') { + console.error('Conflict:', validation.reason); + // "Conflicts with HIGH persistence instruction to use port 27017" +} +``` + +#### 3. Enforce Content Boundaries + +```javascript +const content = "Join thousands of satisfied customers!"; +const validation = await BlogCuration.validateContent(content); + +if (!validation.allowed) { + console.error('Violation:', validation.violations[0]); + // "inst_018: Unverified claim about 'thousands of satisfied customers'" +} +``` + +#### 4. Monitor Context Pressure + +```javascript +const pressure = ContextPressureMonitor.analyzePressure({ + token_usage: 0.75, + conversation_length: 0.80, + task_complexity: 0.60, + error_frequency: 0.10 +}); + +console.log(pressure); +// { +// pressureName: 'ELEVATED', +// overall: 0.5625, +// action: 'REVIEW_BEFORE_COMMIT', +// recommendations: ['Consider creating session handoff'] +// } +``` + +#### 5. Verify Complex Operations + +```javascript +const verification = MetacognitiveVerifier.verify( + "Implement user authentication with JWT and bcrypt", + "I will create middleware, hash passwords, and add protected routes", + { explicit_instructions: await loadInstructions() } +); + +console.log(verification); +// { +// confidence: 0.83, +// decision: 'PROCEED', +// level: 'PROCEED', +// reasoning: '...', +// recommendations: [...] +// } +``` + +--- + +## Database Schema + +### GovernanceRules Collection + +```javascript +{ + _id: ObjectId, + id: "inst_001", // Unique rule identifier + text: "Use MongoDB port 27017", // Instruction text + quadrant: "SYSTEM", // STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM/STORAGE + persistence: "HIGH", // HIGH/MEDIUM/LOW + category: "technical", // content/security/privacy/technical/process/values + priority: 50, // 0-100 + temporalScope: "PERMANENT", // IMMEDIATE/SESSION/PROJECT/PERMANENT + expiresAt: null, // Date or null + active: true, // Boolean + source: "user_instruction", // Origin + stats: { + timesChecked: 42, + timesViolated: 0, + lastChecked: Date + }, + createdAt: Date, + updatedAt: Date +} +``` + +### AuditLogs Collection + +```javascript +{ + _id: ObjectId, + timestamp: Date, + sessionId: "2025-10-11-001", + action: "boundary_enforcement", // Service action type + rulesChecked: ["inst_016", "inst_017", "inst_018"], + violations: [], // Array of violations (if any) + allowed: true, // Decision outcome + metadata: { + // Service-specific context + } +} +``` + +### Documents Collection + +See **Architectural Overview** for complete schema. + +--- + +## Production Deployment + +### 1. Server Setup + +**Recommended**: Ubuntu 22.04 LTS or Debian 12 + +```bash +# Update system +sudo apt update && sudo apt upgrade -y + +# Install Node.js 18 LTS +curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Install MongoDB +wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add - +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 +sudo apt-get update +sudo apt-get install -y mongodb-org + +# Start MongoDB +sudo systemctl start mongod +sudo systemctl enable mongod +``` + +### 2. Deploy Application + +```bash +# Create app user +sudo useradd -m -s /bin/bash tractatus + +# Clone and setup +sudo su - tractatus +git clone https://github.com/AgenticGovernance/tractatus.git +cd tractatus +npm install --production + +# Configure environment +cp .env.example .env +nano .env # Update with production values +``` + +### 3. MongoDB Production Configuration + +```bash +# Create production database user +mongosh +> use tractatus_prod +> db.createUser({ + user: "tractatus_user", + pwd: "SECURE_PASSWORD_HERE", + roles: [ + { role: "readWrite", db: "tractatus_prod" } + ] + }) +> exit + +# Update .env +MONGODB_URI=mongodb://tractatus_user:SECURE_PASSWORD@localhost:27017/tractatus_prod?authSource=tractatus_prod +MONGODB_DB=tractatus_prod +``` + +### 4. systemd Service + +Create `/etc/systemd/system/tractatus.service`: + +```ini +[Unit] +Description=Tractatus AI Safety Framework +Documentation=https://agenticgovernance.digital +After=network.target mongod.service +Requires=mongod.service + +[Service] +Type=simple +User=tractatus +WorkingDirectory=/home/tractatus/tractatus +ExecStart=/usr/bin/node src/server.js +Restart=always +RestartSec=10 +StandardOutput=journal +StandardError=journal +SyslogIdentifier=tractatus + +# Security +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ReadWritePaths=/home/tractatus/tractatus/.memory +MemoryLimit=2G + +# Environment +Environment=NODE_ENV=production + +[Install] +WantedBy=multi-user.target +``` + +**Start service**: + +```bash +sudo systemctl daemon-reload +sudo systemctl start tractatus +sudo systemctl enable tractatus +sudo systemctl status tractatus +``` + +### 5. Nginx Reverse Proxy (Optional) + +```nginx +server { + listen 80; + server_name agenticgovernance.digital; + + location / { + proxy_pass http://localhost:9000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + } +} +``` + +--- + +## Monitoring & Maintenance + +### View Audit Logs + +```bash +# Today's audit trail +cat .memory/audit/decisions-$(date +%Y-%m-%d).jsonl | jq + +# Count violations +cat .memory/audit/*.jsonl | jq 'select(.allowed == false)' | wc -l + +# View specific service logs +cat .memory/audit/*.jsonl | jq 'select(.action == "boundary_enforcement")' +``` + +### MongoDB Queries + +```javascript +// Connect to MongoDB +mongosh mongodb://localhost:27017/tractatus_prod + +// View active rules +db.governanceRules.find({ active: true }).pretty() + +// Check rule statistics +db.governanceRules.aggregate([ + { $match: { active: true } }, + { $group: { + _id: "$quadrant", + count: { $sum: 1 }, + totalChecks: { $sum: "$stats.timesChecked" } + } + } +]) + +// Recent audit logs +db.auditLogs.find().sort({ timestamp: -1 }).limit(10).pretty() +``` + +### Service Health Check + +```bash +# Check service status +sudo systemctl status tractatus + +# View logs +sudo journalctl -u tractatus -f + +# Check MongoDB connection +mongosh --eval "db.adminCommand('ping')" +``` + +--- + +## Troubleshooting + +### Issue: Services not loading rules + +**Symptom**: "Governance rules not initialized" warnings + +**Fix**: +```javascript +// Manually initialize +await InstructionPersistenceClassifier.initialize(); +await CrossReferenceValidator.initialize(); +// etc. +``` + +### Issue: MongoDB connection failed + +**Symptom**: "MongoServerError: Authentication failed" + +**Fix**: +1. Verify `MONGODB_URI` in `.env` +2. Check MongoDB user exists: `mongosh` → `use tractatus_prod` → `db.getUsers()` +3. Verify MongoDB is running: `sudo systemctl status mongod` + +### Issue: API Memory not working + +**Symptom**: Session continuity not preserved + +**Fix**: +- API Memory is **optional** +- Framework functions without it using MongoDB alone +- To enable: Set `CLAUDE_API_KEY` in `.env` + +--- + +## Migration from Filesystem (Legacy) + +If upgrading from filesystem-based instruction storage: + +```bash +# Run migration script +node scripts/migrate-to-mongodb.js + +# Verify migration +mongosh +> use tractatus_dev +> db.governanceRules.countDocuments() +18 # Should show migrated rules +``` + +--- + +## Next Steps + +1. **Read Core Concepts**: Understand the 6 services +2. **Review Architectural Overview**: Complete system architecture +3. **Check Glossary**: Key terms and definitions +4. **Explore Case Studies**: Real-world usage examples + +--- + +## Support + +- **Documentation**: https://agenticgovernance.digital/docs.html +- **GitHub**: https://github.com/AgenticGovernance/tractatus +- **Issues**: https://github.com/AgenticGovernance/tractatus/issues + +--- + +**Version History**: +- v1.1 (2025-10-11): Complete rewrite for MongoDB architecture +- v1.0 (2025-10-07): Initial version (filesystem-based) diff --git a/scripts/update-core-concepts.js b/scripts/update-core-concepts.js new file mode 100644 index 00000000..0c980139 --- /dev/null +++ b/scripts/update-core-concepts.js @@ -0,0 +1,211 @@ +/** + * Update Core Concepts Document for Phase 5 + * Updates service count, adds MongoDB, API Memory, BlogCuration service + */ + +const { MongoClient } = require('mongodb'); +const marked = require('marked'); + +const MONGODB_URI = process.env.MONGODB_URI || 'mongodb://localhost:27017/tractatus_dev'; +const DB_NAME = process.env.MONGODB_DB || 'tractatus_dev'; + +const UPDATES = { + // Update overview section + oldOverview: 'The Tractatus framework consists of five interconnected services that work together to ensure AI operations remain within safe boundaries. Each service addresses a specific aspect of AI safety.', + + newOverview: `The Tractatus framework consists of six interconnected services that work together to ensure AI operations remain within safe boundaries. Each service addresses a specific aspect of AI safety. + +**Current Status**: Production-ready (Phase 5 complete). All services integrated with MongoDB persistence and optional Anthropic API Memory enhancement. + +**Architecture**: Hybrid memory system combining MongoDB (required persistent storage), Anthropic API Memory (optional session enhancement), and filesystem audit trails (debug logging). See the Architectural Overview document for complete technical details.`, + + // Add MongoDB persistence section after service 5 + mongodbSection: ` + +## 6. BlogCuration + +### Purpose + +Validates blog content and social media posts against inst_016-018 governance rules to prevent fabricated statistics, absolute guarantees, and unverified claims. + +### The Problem It Solves + +Marketing content can inadvertently include: +- Fabricated statistics without sources ("95% of users report...") +- Absolute guarantees ("guaranteed 100% secure") +- Unverified customer claims ("thousands of happy customers") + +Without validation, these violations damage credibility and can constitute false advertising. + +### How It Works + +**Validation Process:** + +1. **Rule Loading**: Loads inst_016, inst_017, inst_018 from MongoDB +2. **Content Analysis**: Scans text for violation patterns +3. **Violation Detection**: Identifies specific rule violations +4. **Blocking**: Prevents publication if violations found +5. **Audit Trail**: Logs all validation attempts to MongoDB + +**Enforced Rules:** + +- **inst_016**: No fabricated statistics without validation evidence +- **inst_017**: No absolute guarantees about capabilities +- **inst_018**: No unverified claims about users/customers + +### Example Validation + +\`\`\`javascript +const BlogCuration = require('./services/BlogCuration.service'); + +const blogPost = { + title: "Why Choose Tractatus", + content: "Join thousands of satisfied customers using our framework!" +}; + +const validation = await BlogCuration.validateContent(blogPost.content); + +if (!validation.allowed) { + console.log('Violation:', validation.violations[0]); + // Output: "inst_018: Unverified claim about 'thousands of satisfied customers'" +} +\`\`\` + +### Integration + +- **MongoDB**: Loads governance rules, stores validation logs +- **BoundaryEnforcer**: Shares inst_016-018 enforcement logic +- **Audit Trail**: All validations logged to \`.memory/audit/decisions-{date}.jsonl\` + +--- + +## MongoDB Persistence Architecture + +**Phase 5 Achievement**: All services now persist to MongoDB for production reliability. + +### Collections + +1. **governanceRules**: 18 active instructions (inst_001 through inst_019) +2. **auditLogs**: Decision audit trail with full context +3. **sessionState**: Current session state and token tracking +4. **verificationLogs**: MetacognitiveVerifier confidence scores and decisions +5. **documents**: Framework documentation (this document) + +### Benefits Over Filesystem + +- **Fast indexed queries** by rule ID, quadrant, persistence level +- **Atomic updates** (no race conditions) +- **Aggregation for analytics** (violation patterns, usage stats) +- **Built-in replication** and backup +- **Transaction support** for multi-document operations + +### API Memory Integration (Optional) + +**Anthropic API Memory** provides session continuity but does NOT replace MongoDB: + +- **MongoDB**: Required for persistent storage, production systems +- **API Memory**: Optional enhancement for conversation context +- **Architecture**: Hybrid system with graceful degradation + +If API Memory is unavailable, all services continue functioning with MongoDB alone. + +### Environment Setup + +\`\`\`bash +# Required +MONGODB_URI=mongodb://localhost:27017/tractatus_dev +MONGODB_DB=tractatus_dev + +# Optional (enables API Memory features) +CLAUDE_API_KEY=your_api_key_here +\`\`\` + +See Implementation Guide for complete setup instructions.`, + + // Update "How Services Work Together" section + oldWorkTogether: 'These five services form a complete governance framework', + newWorkTogether: 'These six services form a complete governance framework' +}; + +async function main() { + console.log('=== Updating Core Concepts Document ===\n'); + + let client; + + try { + client = await MongoClient.connect(MONGODB_URI); + const db = client.db(DB_NAME); + const collection = db.collection('documents'); + + // Fetch current document + const doc = await collection.findOne({ slug: 'core-concepts-of-the-tractatus-framework' }); + + if (!doc) { + throw new Error('Core Concepts document not found'); + } + + console.log('Current document loaded'); + console.log(`Current length: ${doc.content_markdown.length} characters\n`); + + // Apply updates + let updated = doc.content_markdown; + + // Update overview + updated = updated.replace(UPDATES.oldOverview, UPDATES.newOverview); + console.log('✓ Updated overview section'); + + // Add BlogCuration and MongoDB sections before "How the Services Work Together" + const insertionPoint = updated.indexOf('## How the Services Work Together'); + if (insertionPoint > -1) { + updated = updated.slice(0, insertionPoint) + UPDATES.mongodbSection + '\n\n' + updated.slice(insertionPoint); + console.log('✓ Added BlogCuration service section'); + console.log('✓ Added MongoDB Persistence Architecture section'); + } else { + console.log('⚠ Could not find insertion point for BlogCuration section'); + } + + // Update "How the Services Work Together" + updated = updated.replace('These five services form a complete governance framework', 'These six services form a complete governance framework'); + console.log('✓ Updated service count in integration section'); + + console.log(`\nNew length: ${updated.length} characters`); + console.log(`Change: +${updated.length - doc.content_markdown.length} characters\n`); + + // Regenerate HTML + const content_html = marked.parse(updated); + + // Update document + const result = await collection.updateOne( + { slug: 'core-concepts-of-the-tractatus-framework' }, + { + $set: { + content_markdown: updated, + content_html: content_html, + 'metadata.date_updated': new Date(), + 'metadata.version': '1.1' + } + } + ); + + if (result.modifiedCount > 0) { + console.log('✓ Document updated in MongoDB'); + console.log('✓ Version updated to 1.1'); + console.log('\n=== Update Complete ==='); + } else { + console.log('⚠ No changes made'); + } + + } catch (error) { + console.error('\n✗ Error:', error.message); + console.error(error.stack); + process.exit(1); + } finally { + if (client) await client.close(); + } +} + +if (require.main === module) { + main(); +} + +module.exports = { main }; diff --git a/scripts/update-glossary.js b/scripts/update-glossary.js new file mode 100644 index 00000000..b782ae86 --- /dev/null +++ b/scripts/update-glossary.js @@ -0,0 +1,186 @@ +/** + * Update Glossary with Phase 5 Terms + * Adds: MemoryProxy, API Memory, Hybrid Architecture, BlogCuration + */ + +const { MongoClient } = require('mongodb'); +const marked = require('marked'); + +const MONGODB_URI = process.env.MONGODB_URI || 'mongodb://localhost:27017/tractatus_dev'; +const DB_NAME = process.env.MONGODB_DB || 'tractatus_dev'; + +const NEW_TERMS = ` + +### MemoryProxy + +**What it means:** A service that manages access to the persistence layer (MongoDB and optionally Anthropic API Memory) for all framework services. + +**Why it matters:** Instead of each service connecting to the database independently, MemoryProxy provides a single, consistent interface. This ensures all services load the same governance rules and log decisions uniformly. + +**Real-world analogy:** Think of it like a library's card catalog system. Instead of everyone wandering the stacks looking for books individually, they all use the same catalog system to find what they need efficiently and consistently. + +**In Tractatus:** MemoryProxy loads the 18 governance rules from MongoDB when services initialize, provides methods to query rules by ID or category, and manages audit log writing. All 6 services (InstructionPersistenceClassifier, CrossReferenceValidator, BoundaryEnforcer, MetacognitiveVerifier, ContextPressureMonitor, BlogCuration) use MemoryProxy to access persistent storage. + +**Technical detail:** Singleton pattern ensures all services share the same MongoDB connection pool and cached rules, improving performance and consistency. + +--- + +### API Memory + +**What it means:** Anthropic's API Memory system that enhances Claude conversations with automatic session context preservation across multiple interactions. + +**Why it matters:** In Phase 5, we integrated API Memory as an *optional enhancement* to our MongoDB-based persistence. API Memory helps maintain conversation continuity, but MongoDB remains the required foundation for governance rules and audit trails. + +**Real-world analogy:** Think of MongoDB as your permanent filing cabinet (required for records) and API Memory as sticky notes on your desk (helpful for current work but not the source of truth). + +**In Tractatus:** API Memory provides session continuity for Claude Code conversations but does NOT replace persistent storage. Our architecture gracefully degrades—if API Memory is unavailable, all services continue functioning with MongoDB alone. + +**Key distinction:** API Memory ≠ Persistent Storage. Governance rules MUST be in MongoDB for production systems. + +--- + +### Hybrid Architecture + +**What it means:** Our Phase 5 architecture that combines three memory layers: MongoDB (required), Anthropic API Memory (optional), and filesystem audit trails (debug). + +**Why it matters:** This layered approach provides both reliability (MongoDB) and enhanced user experience (API Memory) without creating dependencies on external services. If any optional component fails, the system continues operating. + +**Real-world analogy:** Like a car with multiple safety systems—airbags, seatbelts, crumple zones. If one system fails, the others still protect you. + +**In Tractatus:** +- **MongoDB** (Layer 1 - Required): Persistent storage for governance rules, audit logs, session state +- **API Memory** (Layer 2 - Optional): Session continuity enhancement for Claude conversations +- **Filesystem** (Layer 3 - Debug): Local audit trail in \`.memory/audit/\` directory for development + +This architecture achieved 100% framework integration in Phase 5 with zero breaking changes to existing functionality. + +--- + +### BlogCuration + +**What it means:** The sixth framework service (added in Phase 5) that validates blog content and social media posts against inst_016-018 to prevent fabricated statistics, absolute guarantees, and unverified claims. + +**Why it matters:** Marketing content can inadvertently include claims that damage credibility or constitute false advertising. BlogCuration prevents publication of content with governance violations. + +**Real-world analogy:** Like having a legal compliance officer review every press release before publication to ensure no false or misleading claims. + +**In Tractatus:** BlogCuration scans content for patterns like: +- **inst_016**: Fabricated statistics without sources ("95% of users report...") +- **inst_017**: Absolute guarantees about capabilities ("guaranteed 100% secure") +- **inst_018**: Unverified customer claims ("thousands of satisfied customers") + +If violations are detected, publication is blocked until content is corrected. All validation attempts are logged to the audit trail with rule IDs and violation details. + +**Integration:** BlogCuration shares enforcement logic with BoundaryEnforcer and loads rules via MemoryProxy, ensuring consistent governance across all content. + +---`; + +async function main() { + console.log('=== Updating Glossary with Phase 5 Terms ===\n'); + + let client; + + try { + client = await MongoClient.connect(MONGODB_URI); + const db = client.db(DB_NAME); + const collection = db.collection('documents'); + + // Fetch current document + const doc = await collection.findOne({ slug: 'tractatus-agentic-governance-system-glossary-of-terms' }); + + if (!doc) { + throw new Error('Glossary document not found'); + } + + console.log('Current document loaded'); + console.log(`Current length: ${doc.content_markdown.length} characters\n`); + + // Find insertion point (after existing service definitions, before "## Integration" or similar) + let updated = doc.content_markdown; + + // Try to find a good insertion point + const insertionPoints = [ + '### Context Pressure', + '### Metacognitive Verification', + '## Integration', + '## Framework Components' + ]; + + let insertionPoint = -1; + let foundSection = null; + + for (const point of insertionPoints) { + const index = updated.indexOf(point); + if (index > -1) { + insertionPoint = index; + foundSection = point; + break; + } + } + + if (insertionPoint === -1) { + // Fallback: insert before last section + insertionPoint = updated.lastIndexOf('##'); + } + + if (insertionPoint > -1) { + updated = updated.slice(0, insertionPoint) + NEW_TERMS + '\n\n' + updated.slice(insertionPoint); + console.log(`✓ Inserted Phase 5 terms before: ${foundSection || 'last section'}`); + } else { + // Fallback: append to end + updated = updated + '\n\n' + NEW_TERMS; + console.log('✓ Appended Phase 5 terms to end'); + } + + // Update version and date in header + updated = updated.replace('**Version:** 1.0', '**Version:** 1.1'); + updated = updated.replace('**Last Updated:** 2025-10-07', '**Last Updated:** 2025-10-11'); + + console.log(`\nNew length: ${updated.length} characters`); + console.log(`Change: +${updated.length - doc.content_markdown.length} characters\n`); + + // Regenerate HTML + const content_html = marked.parse(updated); + + // Update document + const result = await collection.updateOne( + { slug: 'tractatus-agentic-governance-system-glossary-of-terms' }, + { + $set: { + content_markdown: updated, + content_html: content_html, + 'metadata.date_updated': new Date(), + 'metadata.version': '1.1' + } + } + ); + + if (result.modifiedCount > 0) { + console.log('✓ Glossary updated in MongoDB'); + console.log('✓ Version updated to 1.1'); + console.log('✓ Date updated to 2025-10-11'); + console.log('\n=== Update Complete ==='); + + console.log('\nPhase 5 terms added:'); + console.log(' - MemoryProxy'); + console.log(' - API Memory'); + console.log(' - Hybrid Architecture'); + console.log(' - BlogCuration'); + } else { + console.log('⚠ No changes made'); + } + + } catch (error) { + console.error('\n✗ Error:', error.message); + console.error(error.stack); + process.exit(1); + } finally { + if (client) await client.close(); + } +} + +if (require.main === module) { + main(); +} + +module.exports = { main };