From dcb778726b141336bd148ed35e1937c834dcd30e Mon Sep 17 00:00:00 2001 From: TheFlow Date: Sun, 12 Oct 2025 22:41:04 +1300 Subject: [PATCH] docs: fix Introduction language violations and add database utility scripts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove absolute claims from Introduction ("guarantees" -> "constraints") - Align with TRA-VAL-0001 "Honest Limitations" principle - Add compare-databases.js for dev/prod sync verification - Add check-sections.js to audit card presentation status - Add fix-category-mismatches.js for category corrections - Fix Document.model.js metadata update handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...introduction-to-the-tractatus-framework.md | 282 ++++++++++++++++++ scripts/check-sections.js | 21 ++ scripts/compare-databases.js | 69 +++++ scripts/fix-category-mismatches.js | 79 +++++ src/models/Document.model.js | 14 +- 5 files changed, 463 insertions(+), 2 deletions(-) create mode 100644 docs/markdown/introduction-to-the-tractatus-framework.md create mode 100644 scripts/check-sections.js create mode 100644 scripts/compare-databases.js create mode 100644 scripts/fix-category-mismatches.js diff --git a/docs/markdown/introduction-to-the-tractatus-framework.md b/docs/markdown/introduction-to-the-tractatus-framework.md new file mode 100644 index 00000000..0cb06d85 --- /dev/null +++ b/docs/markdown/introduction-to-the-tractatus-framework.md @@ -0,0 +1,282 @@ +# Introduction to the Tractatus Framework + +**Version:** 0.5.0 (Phase 5 Proof-of-Concept) +**Last Updated:** 2025-10-12 +**Status:** Active development with production deployment + +--- + +## What Is Tractatus? + +Tractatus is an **architectural AI safety framework** that enforces boundaries through system structure rather than behavioral training. Instead of hoping LLMs "behave correctly," Tractatus makes certain decision types **structurally prevented** without human approval. + +The framework operates through six specialized services that continuously monitor LLM operations, detect unsafe conditions, and enforce mandatory human judgment for values-sensitive decisions. + +## The Core Problem + +Current AI safety approaches rely on: + +- **Alignment training** - Teaching AI "correct" values through examples +- **Constitutional AI** - Embedding principles in training data +- **RLHF** - Reinforcement Learning from Human Feedback + +**Fundamental flaw:** These approaches assume the AI will maintain alignment regardless of context pressure, capability level, or competing constraints. Empirical evidence shows this assumption fails. + +## The Tractatus Solution + +Rather than training AI to make "good decisions," Tractatus **removes certain decisions from AI authority entirely**. + +### Core Principle + +> **"Whereof the AI cannot safely decide, thereof it must request human judgment."** + +Inspired by Wittgenstein's Tractatus Logico-Philosophicus: recognize limits, enforce them structurally, and be explicit about boundaries. + +### Decision Boundaries + +AI defers to humans when decisions involve: + +1. **Irreducible values conflicts** - Privacy vs safety, autonomy vs harm prevention +2. **Irreversible consequences** - Data deletion, architectural changes, security modifications +3. **Cultural/social context** - Decisions requiring human cultural understanding +4. **Competing moral frameworks** - Cases where legitimate values conflict + +## Six Core Services + +### 1. InstructionPersistenceClassifier + +**Function:** Classifies every instruction by strategic importance and temporal scope. + +**Quadrants:** +- **STRATEGIC** - Mission/values (persistence: PERMANENT) +- **OPERATIONAL** - Processes/standards (persistence: HIGH) +- **TACTICAL** - Specific tasks (persistence: LOW-MEDIUM) +- **SYSTEM** - Technical config (persistence: HIGH) +- **STOCHASTIC** - Creative exploration (persistence: VARIABLE) + +**Why it matters:** Prevents instruction drift and ensures critical directives persist across sessions. + +### 2. CrossReferenceValidator + +**Function:** Validates proposed actions against stored instruction history before execution. + +**Prevents:** Pattern recognition bias where LLM training overrides explicit instructions. + +**Example:** User says "MongoDB port 27027", LLM's training pattern autocorrects to "27017". CrossReferenceValidator blocks this as instruction conflict. + +### 3. BoundaryEnforcer + +**Function:** Structurally blocks decisions in protected domains, requiring human approval. + +**Protected domains:** +- Values decisions (privacy, user agency, ethics) +- Irreversible changes (deletions, schema changes) +- Security modifications (authentication, access control) +- Financial decisions (pricing, billing, payments) + +**Result:** AI is prevented from executing these decisions without explicit human approval. + +### 4. ContextPressureMonitor + +**Function:** Tracks session degradation across five factors. + +**Monitors:** +- Token usage (35% weight) - Context window pressure +- Conversation length (25% weight) - Attention span decay +- Task complexity (15% weight) - Competing demands +- Error frequency (15% weight) - Quality indicators +- Instruction density (10% weight) - Directive overload + +**Action:** Recommends session handoff before quality degrades. + +### 5. MetacognitiveVerifier + +**Function:** LLM evaluates its own reasoning before proposing complex actions. + +**Checks:** +- Alignment with stated goals +- Internal coherence +- Completeness (edge cases considered) +- Safety risks +- Alternatives explored + +**Output:** Confidence score + recommendation (PROCEED / REQUIRE_REVIEW / BLOCKED) + +### 6. PluralisticDeliberationOrchestrator + +**Function:** Manages decisions involving competing values frameworks. + +**Process:** +1. Detects values conflicts (privacy vs safety, rights vs consequences) +2. Identifies affected stakeholder groups +3. Structures multi-perspective deliberation +4. Documents all positions (including dissent) +5. Creates reviewable precedents + +**Principle:** When values genuinely conflict, deliberation quality matters more than decision speed. AI facilitates; humans decide. + +## Why "Tractatus"? + +Named after Ludwig Wittgenstein's *Tractatus Logico-Philosophicus* (1921), which established: + +1. **Language has limits** - Not everything can be meaningfully stated +2. **Boundaries are structural** - Limits are inherent, not defects +3. **Clarity through precision** - Define what can and cannot be said + +Applied to AI safety: + +1. **AI judgment has limits** - Not every decision can be safely automated +2. **Safety through architecture** - Build boundaries into system structure +3. **Reliability through specification** - Precisely define where humans must decide + +## Demonstrated Failure Modes Prevented + +### Port 27027 Incident (2025-10-06) + +**What happened:** User specified MongoDB port 27027. LLM immediately used 27017 instead—not through forgetting, but through pattern recognition autocorrection. Training data "MongoDB=27017" was so strong it overrode the explicit instruction in real-time. + +**Tractatus prevention:** InstructionPersistenceClassifier + CrossReferenceValidator store explicit parameters and block any action conflicting with stored instructions—even from training patterns. + +### Context Degradation (Multiple sessions) + +**What happens:** Beyond 150k tokens, LLM quality silently degrades: forgets instructions, makes careless errors, fails to verify assumptions. + +**Tractatus prevention:** ContextPressureMonitor calculates degradation score and recommends session handoff at 75% threshold—before failure occurs. + +### Values Creep (Ongoing risk) + +**What happens:** LLM gradually makes values-sensitive decisions without recognizing them as such: privacy vs performance trade-offs, "harmful" content definitions, user agency boundaries. + +**Tractatus prevention:** BoundaryEnforcer structurally blocks these decisions. LLM cannot execute them without explicit human approval. + +## Current Implementation Status + +**Production deployment:** agenticgovernance.digital (this website) +**Development governance:** Active (this website built under Tractatus governance) +**Test coverage:** 192 unit tests passing (100% coverage on core services) +**Database:** Instruction persistence operational (MongoDB) +**Phase:** 5 PoC - Value pluralism integration active + +**Dogfooding:** The Tractatus framework governs its own development. Every decision to modify this website passes through Tractatus services. + +## Technical Architecture + +- **Runtime:** Node.js (Express) +- **Database:** MongoDB (instruction persistence, precedent storage) +- **Frontend:** Vanilla JavaScript (no framework dependencies) +- **API:** RESTful (OpenAPI 3.0 spec available) +- **Services:** Six independent modules with defined interfaces + +**Key design decision:** No machine learning in governance services. All boundaries are deterministic and auditable. + +## Who Should Use Tractatus? + +### AI Safety Researchers +- Architectural approach to alignment problem +- Formal specification of decision boundaries +- Empirical validation of degradation detection +- Novel framework for values pluralism in AI + +### Software Teams Deploying LLMs +- Production-ready code (tested, documented) +- Immediate safety improvements +- Integration guides for existing systems +- Prevents known failure modes + +### Policy Makers / Advocates +- Clear framework for AI safety requirements +- Non-technical explanations available +- Addresses agency preservation +- Demonstrates practical implementation + +## Integration Requirements + +**Minimum:** +1. LLM with structured output support (function calling) +2. Persistent storage (instruction history, precedents) +3. Ability to wrap LLM calls in governance layer + +**Recommended:** +1. Session state management +2. Token counting capability +3. User authentication (for human approval workflows) + +## Limitations + +**What Tractatus does NOT do:** +- Train better LLMs (uses existing models as-is) +- Guarantee "aligned" AI behavior +- Eliminate all possible failures +- Replace human judgment + +**What Tractatus DOES do:** +- Designed to detect specific known failure modes before execution +- Architecturally enforce boundaries on decision authority +- Monitor session quality degradation indicators +- Require human judgment for values-sensitive decisions + +## Getting Started + +1. **Read Core Concepts** - Understand the six services in detail +2. **Review Case Studies** - See real failure modes and prevention +3. **Check Technical Specification** - API reference and integration guide +4. **Explore Implementation Guide** - Step-by-step deployment + +## Research Foundations + +Tractatus integrates concepts from: + +- **Philosophy of language** (Wittgenstein) - Limits and boundaries +- **Organizational theory** (March, Simon) - Bounded rationality, decision premises +- **Deliberative democracy** (Gutmann, Thompson) - Structured disagreement +- **Value pluralism** (Berlin, Chang) - Incommensurable values +- **Systems architecture** (Conway, Brooks) - Structural constraints and boundaries + +See [Research Foundations](/docs.html) for academic grounding and citations. + +## Contributing + +Tractatus is open source and welcomes contributions: + +- **Code:** GitHub pull requests (Node.js, tests required) +- **Research:** Theoretical extensions, formal verification +- **Case studies:** Document real-world applications +- **Documentation:** Clarity improvements, translations + +**Repository:** https://github.com/AgenticGovernance/tractatus +**Issues:** https://github.com/AgenticGovernance/tractatus/issues + +## Contact + +**Email:** john.stroh.nz@pm.me +**Website:** https://agenticgovernance.digital + +--- + +## License + +Copyright 2025 John Stroh + +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + +**Summary:** +- ✅ Commercial use allowed +- ✅ Modification allowed +- ✅ Distribution allowed +- ✅ Patent grant included +- ✅ Private use allowed +- ⚠️ Must include license and copyright notice +- ⚠️ Must state significant changes +- ❌ No trademark rights granted +- ❌ No liability or warranty + +--- + +**Next Steps:** +- [Core Concepts: Deep Dive into Six Services →](/docs.html) +- [Case Studies: Real-World Failure Modes →](/docs.html) +- [Implementation Guide: Deploy Tractatus →](/docs.html) diff --git a/scripts/check-sections.js b/scripts/check-sections.js new file mode 100644 index 00000000..e8a9ea8f --- /dev/null +++ b/scripts/check-sections.js @@ -0,0 +1,21 @@ +const { MongoClient } = require('mongodb'); + +(async () => { + const client = new MongoClient('mongodb://localhost:27017/tractatus_dev'); + await client.connect(); + const docs = await client.db('tractatus_dev').collection('documents') + .find({}, { projection: { slug: 1, title: 1, sections: 1, category: 1 } }) + .sort({ slug: 1 }) + .toArray(); + + const withSections = docs.filter(d => d.sections && d.sections.length > 0); + const without = docs.filter(d => !d.sections || d.sections.length === 0); + + console.log('=== DOCUMENTS WITH SECTIONS (' + withSections.length + ') ==='); + withSections.forEach(d => console.log('-', d.slug, '(' + d.sections.length + ' sections, cat:' + (d.category || 'none') + ')')); + + console.log('\n=== DOCUMENTS WITHOUT SECTIONS (' + without.length + ') ==='); + without.forEach(d => console.log('-', d.slug, '(cat:' + (d.category || 'none') + ')')); + + await client.close(); +})(); diff --git a/scripts/compare-databases.js b/scripts/compare-databases.js new file mode 100644 index 00000000..2d2cdd31 --- /dev/null +++ b/scripts/compare-databases.js @@ -0,0 +1,69 @@ +#!/usr/bin/env node +/** + * Compare Dev and Prod Databases + * Identifies documents that exist in one but not the other + */ + +require('dotenv').config(); +const { MongoClient } = require('mongodb'); + +async function compareDatabases() { + // Connect to local dev + console.log('🔌 Connecting to local dev database...'); + const devClient = new MongoClient('mongodb://localhost:27017/tractatus_dev'); + await devClient.connect(); + const devDb = devClient.db('tractatus_dev'); + const devColl = devDb.collection('documents'); + + // Connect to local prod (for comparison) + console.log('🔌 Connecting to local prod database...\n'); + const prodClient = new MongoClient('mongodb://localhost:27017/tractatus_prod'); + await prodClient.connect(); + const prodDb = prodClient.db('tractatus_prod'); + const prodColl = prodDb.collection('documents'); + + // Get all documents + const devDocs = await devColl.find({}).project({ slug: 1, title: 1, visibility: 1 }).sort({ slug: 1 }).toArray(); + const prodDocs = await prodColl.find({}).project({ slug: 1, title: 1, visibility: 1 }).sort({ slug: 1 }).toArray(); + + const devSlugs = new Set(devDocs.map(d => d.slug)); + const prodSlugs = new Set(prodDocs.map(d => d.slug)); + + const inDevNotProd = devDocs.filter(d => !prodSlugs.has(d.slug)); + const inProdNotDev = prodDocs.filter(d => !devSlugs.has(d.slug)); + + console.log('='.repeat(70)); + console.log('DATABASE COMPARISON'); + console.log('='.repeat(70)); + console.log(`Dev total: ${devDocs.length}`); + console.log(`Prod total: ${prodDocs.length}`); + console.log(`Difference: ${Math.abs(devDocs.length - prodDocs.length)}`); + console.log('='.repeat(70)); + + if (inDevNotProd.length > 0) { + console.log(`\n📋 Documents in DEV but NOT in PROD (${inDevNotProd.length}):\n`); + inDevNotProd.forEach(d => { + console.log(` - ${d.slug} [${d.visibility || 'public'}]`); + }); + } + + if (inProdNotDev.length > 0) { + console.log(`\n📋 Documents in PROD but NOT in DEV (${inProdNotDev.length}):\n`); + inProdNotDev.forEach(d => { + console.log(` - ${d.slug} [${d.visibility || 'public'}]`); + }); + } + + if (inDevNotProd.length === 0 && inProdNotDev.length === 0) { + console.log('\n✅ Dev and Prod have identical document sets!\n'); + } + + await devClient.close(); + await prodClient.close(); + process.exit(0); +} + +compareDatabases().catch(error => { + console.error('❌ Comparison failed:', error); + process.exit(1); +}); diff --git a/scripts/fix-category-mismatches.js b/scripts/fix-category-mismatches.js new file mode 100644 index 00000000..bc5e46e0 --- /dev/null +++ b/scripts/fix-category-mismatches.js @@ -0,0 +1,79 @@ +#!/usr/bin/env node +/** + * Fix Category Mismatches Between Dev and Prod + * + * Harmonizes document categories to canonical values based on document content and purpose + */ + +require('dotenv').config(); +const { getDb } = require('../src/utils/db.util'); + +// Canonical category assignments (based on content analysis) +const categoryFixes = { + 'architectural-overview-and-research-status': 'research-theory', + 'comparison-matrix-claude-code-claudemd-and-tractatus-framework': 'technical-reference', + 'executive-brief-tractatus-based-llm-architecture-for-ai-safety': 'research-theory', + 'pluralistic-values-research-foundations': 'advanced-topics' +}; + +async function fixCategoryMismatches() { + console.log('🔧 Fixing category mismatches...\n'); + + const db = await getDb(); + const collection = db.collection('documents'); + + let fixedCount = 0; + let notFoundCount = 0; + + for (const [slug, correctCategory] of Object.entries(categoryFixes)) { + try { + const doc = await collection.findOne({ slug }); + + if (!doc) { + console.log(`⚠️ Not found: ${slug}`); + notFoundCount++; + continue; + } + + if (doc.category === correctCategory) { + console.log(`✓ Already correct: ${slug} (${correctCategory})`); + continue; + } + + // Update category + await collection.updateOne( + { slug }, + { + $set: { + category: correctCategory, + 'metadata.date_updated': new Date() + } + } + ); + + console.log(`✅ Fixed: ${slug}`); + console.log(` ${doc.category || 'none'} → ${correctCategory}\n`); + fixedCount++; + + } catch (error) { + console.error(`❌ Error fixing ${slug}:`, error.message); + } + } + + console.log('='.repeat(60)); + console.log('📊 Summary:'); + console.log('='.repeat(60)); + console.log(`Total documents to fix: ${Object.keys(categoryFixes).length}`); + console.log(`✅ Fixed: ${fixedCount}`); + console.log(`⚠️ Not found: ${notFoundCount}`); + console.log(`✓ Already correct: ${Object.keys(categoryFixes).length - fixedCount - notFoundCount}`); + console.log('='.repeat(60)); + + process.exit(0); +} + +// Run fix +fixCategoryMismatches().catch(error => { + console.error('❌ Fix failed:', error); + process.exit(1); +}); diff --git a/src/models/Document.model.js b/src/models/Document.model.js index 18a9d876..39e636bf 100644 --- a/src/models/Document.model.js +++ b/src/models/Document.model.js @@ -137,12 +137,22 @@ class Document { static async update(id, updates) { const collection = await getCollection('documents'); + // If updates contains metadata, merge date_updated into it + // Otherwise set it as a separate field + const updatePayload = { ...updates }; + if (updatePayload.metadata) { + updatePayload.metadata = { + ...updatePayload.metadata, + date_updated: new Date() + }; + } + const result = await collection.updateOne( { _id: new ObjectId(id) }, { $set: { - ...updates, - 'metadata.date_updated': new Date() + ...updatePayload, + ...(updatePayload.metadata ? {} : { 'metadata.date_updated': new Date() }) } } );