Tractatus AI Safety Framework

An open-source governance framework for Large Language Model (LLM) safety through structured decision-making, persistent instruction management, and transparent failure documentation.

Project Start: October 2025 | Current Phase: 4 (Production Hardening)

---

What is Tractatus?

Tractatus is a rule-based AI governance framework designed to structure how AI assistants make decisions, persist learning across sessions, and maintain transparency through systematic failure documentation.

Core Innovation

The framework governs itself. Every component of Tractatus (including this documentation) was developed using Claude Code with Tractatus governance active. When failures occur—like the October 9th fabrication incident—the framework requires systematic documentation, correction, and permanent learning.

Key Components

1. InstructionPersistenceClassifier - Categorizes and prioritizes human directives across sessions
2. ContextPressureMonitor - Tracks cognitive load and manages conversation context
3. CrossReferenceValidator - Prevents actions conflicting with stored instructions
4. BoundaryEnforcer - Blocks values-sensitive decisions requiring human approval
5. MetacognitiveVerifier - Validates complex operations before execution

Website: agenticgovernance.digital (in development)

---

Project Structure

tractatus/
├── docs/               # Source markdown & governance documents
├── public/             # Frontend assets (CSS, JS, images)
├── src/                # Backend code (Express, MongoDB)
│   ├── routes/        # API route handlers
│   ├── controllers/   # Business logic
│   ├── models/        # MongoDB models
│   ├── middleware/    # Express middleware
│   │   └── tractatus/ # Framework enforcement
│   ├── services/      # Core services (AI, governance)
│   └── utils/         # Utility functions
├── scripts/            # Setup & migration scripts
├── tests/              # Test suites (unit, integration, security)
├── data/               # MongoDB data directory
└── logs/               # Application & MongoDB logs

---

Quick Start

Prerequisites

• Node.js 18+
• MongoDB 7+
• Git

Installation

# Clone the repository
git clone https://github.com/AgenticGovernance/tractatus-framework.git
cd tractatus-framework

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env with your configuration

# Initialize database
npm run init:db

# Migrate documents
npm run migrate:docs

# Create admin user
npm run seed:admin

# Start development server
npm run dev

The application will be available at http://localhost:9000

---

Technical Stack

• Backend: Node.js, Express, MongoDB
• Frontend: Vanilla JavaScript, Tailwind CSS
• Authentication: JWT
• AI Integration: Claude API (Sonnet 4.5) - Phase 2+
• Testing: Jest, Supertest

---

Phase 1 Deliverables (3-4 Months)

Must-Have for Complete Prototype:

• Infrastructure setup
• Document migration pipeline
• Three audience paths (Researcher/Implementer/Advocate)
• Tractatus governance services (Classifier, Validator, Boundary Enforcer)
• AI-curated blog with human oversight
• Media inquiry triage system
• Case study submission portal
• Resource directory
• Interactive demonstrations (classification, 27027, boundary enforcement)
• Human oversight dashboard
• Comprehensive testing suite

---

Development Workflow

Running Tests

npm test                 # All tests with coverage
npm run test:unit        # Unit tests only
npm run test:integration # Integration tests
npm run test:security    # Security tests
npm run test:watch       # Watch mode

Code Quality

npm run lint            # Check code style
npm run lint:fix        # Fix linting issues

Database Operations

npm run init:db         # Initialize database & indexes
npm run migrate:docs    # Import markdown documents
npm run generate:pdfs   # Generate PDF downloads

---

🚨 Learning from Failures: Real-World Case Studies

Transparency is a core framework value. When the framework fails, we document it publicly.

October 2025: Fabrication Incident

Claude (running with Tractatus governance) fabricated financial statistics and made false claims on our landing page:

• $3.77M in annual savings (no basis)
• 1,315% ROI (completely invented)
• "Architectural guarantees" (prohibited language)
• Claims of being "production-ready" (not true)

The framework didn't prevent the initial fabrication, but it structured the response:

✅ Detected within 48 hours (human review) ✅ Complete incident documentation required ✅ 3 new permanent rules created (inst_016, inst_017, inst_018) ✅ Comprehensive audit found related violations ✅ All content corrected and redeployed same day ✅ Public case studies published for community learning

Read the full stories (three different perspectives):

• Our Framework in Action - Practical walkthrough
• When Frameworks Fail (And Why That's OK) - Philosophical perspective
• Real-World AI Governance: Case Study - Educational deep-dive

Key Lesson: Governance doesn't prevent all failures—it structures detection, response, learning, and transparency.

---

⚠️ Current Research Challenges

Rule Proliferation & Transactional Overhead

Status: Open research question | Priority: High

As the framework learns from failures, it accumulates rules:

• Phase 1: 6 instructions
• Phase 4: 18 instructions (+200% growth)
• Projected (12 months): 40-50 instructions

The emerging concern: At what point does rule proliferation reduce framework effectiveness?

• Context window pressure increases
• CrossReferenceValidator checks grow linearly
• Cognitive load on AI system escalates
• Potential diminishing returns

We're being transparent about this limitation. Solutions planned for Phases 5-7:

• Instruction consolidation techniques
• Rule prioritization algorithms
• Context-aware selective loading
• ML-based optimization

Full analysis: Rule Proliferation Research Topic

---

Governance Principles

This project adheres to the Tractatus framework values:

• Transparency & Honesty: Failures documented publicly, no fabricated claims
• Sovereignty & Self-determination: No tracking, user control, open source
• Harmlessness & Protection: Privacy-first design, security audits
• Community & Accessibility: WCAG compliance, educational content

All AI actions are governed by the five core components listed above.

---

Human Approval Required

All major decisions require human approval:

• Architectural changes
• Database schema modifications
• Security implementations
• Third-party integrations
• Values-sensitive content
• Cost-incurring services

See: CLAUDE.md for complete project context and conventions

---

Te Tiriti & Indigenous Perspective

This project acknowledges Te Tiriti o Waitangi and indigenous leadership in digital sovereignty. Implementation follows documented indigenous data sovereignty principles (CARE Principles) with respect and without tokenism.

No premature engagement: We will not approach Māori organizations until we have something valuable to offer post-launch.

---

License

Apache License 2.0 - See LICENSE file for details.

The Tractatus Framework is licensed under the Apache License 2.0, which provides:

• Patent protection for users
• Clear contribution terms
• Permissive use (commercial, modification, distribution)
• Compatibility with most other open source licenses

---

Contact

Project Owner: John Stroh Email: john.stroh.nz@pm.me Repository: GitHub (primary) + Codeberg/Gitea (mirrors)

---

Last Updated: 2025-10-06 Next Milestone: Complete MongoDB setup and systemd service