john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: Phase 2 - Update documentation for Phase 5 MongoDB architecture

Browse source 
Content Updates (3 documents):

1. Core Concepts (v1.0 → v1.1):
   - Updated from 5 to 6 services (added BlogCuration)
   - Added MongoDB Persistence Architecture section
   - Added API Memory integration explanation
   - Added Hybrid Architecture details
   - Added BlogCuration service documentation
   - References Architectural Overview for complete details
   - +3,249 characters

2. Implementation Guide (v1.0 → v1.1):
   - Complete rewrite for MongoDB architecture
   - Removed non-existent npm package references
   - Added MongoDB setup (local + Atlas)
   - Added environment configuration (.env)
   - Added service initialization examples
   - Added database schema documentation
   - Added production deployment guide (systemd)
   - Added monitoring & troubleshooting
   - Added migration guide from filesystem
   - Reduced from 17,726 to 12,925 characters (more focused)

3. Glossary (v1.0 → v1.1):
   - Added MemoryProxy definition
   - Added API Memory definition
   - Added Hybrid Architecture definition
   - Added BlogCuration definition
   - Updated version to 1.1
   - Updated date to 2025-10-11
   - +4,435 characters

Scripts Created:
- scripts/update-core-concepts.js: Automated Core Concepts update
- scripts/update-glossary.js: Automated Glossary term additions
- docs/markdown/implementation-guide-v1.1.md: New Implementation Guide source

PDFs Regenerated:
- core-concepts-of-the-tractatus-framework.pdf
- implementation-guide.pdf
- tractatus-agentic-governance-system-glossary-of-terms.pdf

All 3 documents now accurate for Phase 5 MongoDB architecture.

Next: Deploy to production

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
TheFlow 2025-10-11 01:35:24 +13:00
parent 6ceac8f449
commit ff9dc35ba7
3 changed files with 941 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

544
docs/markdown/implementation-guide-v1.1.md Normal file
View file

@ -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)

211
scripts/update-core-concepts.js Normal file
View file

@ -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 };

186
scripts/update-glossary.js Normal file
View file

@ -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 };