Tractatus Framework

Last Updated: 2025-11-02

Architectural AI Safety Through Structural Constraints

One research framework for enforcing AI safety through architectural constraints rather than training-based alignment. We think this approach works at scale, but we're finding out through production testing. Tractatus preserves human agency through structural, not aspirational enforcement of decision boundaries.

---

🎯 What is Tractatus?

Organizations are deploying amoral AI systems at scale—agents making thousands of decisions daily with no moral grounding to navigate value conflicts. Tractatus is one architectural approach that provides governance mechanisms for plural moral values, not imposed frameworks.

It makes certain values-sensitive decisions structurally impossible for AI systems to make without human judgment. Unlike traditional AI safety approaches that rely on training and alignment, Tractatus uses runtime enforcement of decision boundaries.

The Core Problem

Traditional AI safety relies on:

• 🎓 Alignment training - Hoping the AI learns the "right" values
• 📜 Constitutional AI - Embedding principles in training
• 🔄 RLHF - Reinforcement learning from human feedback

These approaches share a fundamental flaw: they assume the AI will maintain alignment regardless of capability or context pressure.

The Tractatus Solution

Tractatus implements architectural constraints that:

• ✅ Block values decisions - Privacy vs. performance requires human judgment
• ✅ Prevent instruction override - Explicit instructions can't be autocorrected by training patterns
• ✅ Detect context degradation - Quality metrics trigger session handoffs
• ✅ Require verification - Complex operations need metacognitive checks
• ✅ Persist instructions - Directives survive across sessions
• ✅ Facilitate pluralistic deliberation - Multi-stakeholder values conflicts require structured process

---

🚀 Quick Start

Installation

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

# Install dependencies
npm install

# Initialize database
npm run init:db

# Start development server
npm run dev

Basic Usage

const {
  InstructionPersistenceClassifier,
  CrossReferenceValidator,
  BoundaryEnforcer,
  ContextPressureMonitor,
  MetacognitiveVerifier,
  PluralisticDeliberationOrchestrator
} = require('./src/services');

// Classify an instruction
const classifier = new InstructionPersistenceClassifier();
const classification = classifier.classify({
  text: "Always use MongoDB on port 27027",
  source: "user"
});

// Store in instruction history
await InstructionDB.store(classification);

// Validate before taking action
const validator = new CrossReferenceValidator();
const validation = await validator.validate({
  type: 'database_config',
  port: 27017  // ⚠️ Conflicts with stored instruction!
});

// validation.status === 'REJECTED'
// validation.reason === 'Pattern recognition bias override detected'

---

📚 Core Components

The framework consists of six integrated services that work together to enforce structural safety:

1. InstructionPersistenceClassifier

Classifies instructions by quadrant and persistence level:

{
  quadrant: "SYSTEM",           // STRATEGIC | OPERATIONAL | TACTICAL | SYSTEM | STOCHASTIC
  persistence: "HIGH",           // HIGH | MEDIUM | LOW | VARIABLE
  temporal_scope: "PROJECT",     // SESSION | PROJECT | PERMANENT
  verification_required: "MANDATORY"
}

2. CrossReferenceValidator

Prevents the "27027 failure mode" where AI training patterns override explicit instructions:

const result = validator.validate(action, { explicit_instructions });
// Blocks: Training pattern overrides, parameter conflicts, scope creep

3. BoundaryEnforcer

Blocks decisions that cross into values territory:

const check = enforcer.checkBoundary({
  decision: "Update privacy policy for more tracking"
});
// Result: BLOCKED - Values decision requires human judgment

4. ContextPressureMonitor

Multi-factor session health tracking:

const pressure = monitor.analyze({
  tokens: 120000/200000,      // 60% token usage
  messages: 45,                // Conversation length
  tasks: 8,                    // Concurrent complexity
  errors: 3                    // Recent error count
});
// Level: ELEVATED | Recommendation: INCREASE_VERIFICATION

5. MetacognitiveVerifier

AI self-checks reasoning before proposing actions:

const verification = verifier.verify({
  action: "Refactor 47 files across 5 system areas",
  context: { requested: "Refactor authentication module" }
});
// Decision: REQUIRE_REVIEW (scope creep detected)

6. PluralisticDeliberationOrchestrator

Facilitates multi-stakeholder deliberation when values frameworks conflict. Organizations configure boundaries based on their values—we don't impose "best practices" or resolve conflicts. When efficiency conflicts with safety, data utility conflicts with privacy, or other incommensurable values arise, the system ensures humans deliberate based on organizational context:

const deliberation = orchestrator.initiate({
  decision: "Balance user privacy vs. system security logging",
  stakeholders: ["data_subjects", "security_team", "compliance"],
  conflict_type: "incommensurable_values"
});
// AI facilitates deliberation structure, humans decide outcome

Full documentation: agenticgovernance.digital/docs.html

---

⚙️ Current Capabilities & Limitations

What Tractatus CAN Do Today

✅ Hook-Triggered Governance (Production-Tested, 6 months)

• Validates every Edit/Write/Bash operation before execution via Claude Code hooks
• Blocks operations violating governance rules (31/39 rules automated - 79%)
• Average overhead: 47ms per validation (imperceptible to developers)
• Full audit trail: Every decision logged to MongoDB with service attribution

✅ Historical Pattern Learning (Filesystem + Agent Lightning Integration)

• Stores governance decisions in .claude/observations/ directory
• Semantic search over past decisions (via Agent Lightning port 5001)
• Cross-session persistence (survives auto-compacts and session restarts)
• Pattern warnings: "3 previous edits to this file under HIGH pressure caused rollback"

✅ Proactive Warnings Before Tool Execution

• Analyzes risk based on historical patterns using SessionObserver service
• Risk levels: LOW | MEDIUM | HIGH | CRITICAL with confidence scores
• Warnings injected into Claude Code context before governance validation
• Recommendations: PROCEED | PROCEED_WITH_CAUTION | REVIEW_REQUIRED

✅ Six Integrated Framework Services (Documented Above)

• BoundaryEnforcer: Values decisions require human judgment
• CrossReferenceValidator: Prevents training pattern overrides ("27027 incident")
• MetacognitiveVerifier: AI self-checks confidence before proposing actions
• ContextPressureMonitor: Detects session quality degradation
• InstructionPersistenceClassifier: Maintains instruction consistency
• PluralisticDeliberationOrchestrator: Facilitates multi-stakeholder deliberation

What Tractatus CANNOT Do (Requires External Agent Partner)

❌ Continuous Awareness Between Tool Calls

• Hooks only trigger when Claude Code calls Edit/Write/Bash
• No observation during AI reasoning process (between tool invocations)
• Cannot detect "I'm planning a bad decision" before attempting tool execution
• Implication: Gaps exist between my reasoning and action

❌ Catching Reasoning Errors in Conversation

• Hooks validate tool calls only, not conversational responses
• Cannot detect wrong advice, incorrect explanations, or fabricated claims in text
• User must identify conversational errors before they become executable actions
• Implication: Governance applies to actions, not all outputs

❌ True Autonomous Agent Monitoring From Outside

• Not a separate process watching Claude Code externally
• Cannot observe Claude Code from outside its own execution context
• Requires Claude Code lifecycle events to trigger (hook-dependent architecture)
• Implication: Cannot replace human oversight, only augments it

Why External Agent Required for Full Coverage

To achieve comprehensive monitoring (catching mistakes before they become tool calls):

Requirements:

• External process monitoring Claude Code session logs in real-time
• Analysis of conversational responses (not just executable actions)
• Continuous observation between AI responses (independent event loop)
• Integration with Claude Code via session log streaming or similar protocol

Technology Stack: Agent Lightning framework, session log monitoring, real-time semantic analysis

Tractatus Provides: Interface for external agents (observations API, semantic search, governance rules schema, integration protocols)

Partner Opportunity: We're seeking collaborators to build the external monitoring agent component. Tractatus governance services provide the foundation; external agent provides continuous coverage.

Contact: john.stroh.nz@pm.me | Subject: "External Agent Partnership"

---

💡 Real-World Examples

The 27027 Incident

Problem: User explicitly instructs "Use MongoDB on port 27027". AI immediately uses port 27017 instead.

Why: Training pattern "MongoDB = 27017" overrides explicit instruction, like autocorrect changing a deliberately unusual word.

Solution: CrossReferenceValidator blocks the action and enforces user's explicit instruction.

Try the Interactive Demo →

Context Degradation

Problem: In extended sessions, error rates increase as context degrades.

Solution: ContextPressureMonitor detects degradation and triggers session handoff before quality collapses.

Values Creep

Problem: "Improve performance" request leads AI to suggest weakening privacy protections without asking.

Solution: BoundaryEnforcer blocks the privacy/performance trade-off and requires human decision.

---

🚨 Learning from Failures: Transparency in Action

The framework doesn't prevent all failures—it structures detection, response, and learning.

October 2025: AI Fabrication Incident

During development, Claude (running with Tractatus governance) fabricated financial statistics on the landing page:

• $3.77M in annual savings (no basis)
• 1,315% ROI (completely invented)
• False readiness claims (unverified maturity statements)

The framework structured the response:

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

Read the full case studies:

• Our Framework in Action - Practical walkthrough
• When Frameworks Fail - Philosophical perspective
• Real-World Governance - Educational analysis

Key Lesson: Governance doesn't ensure perfection—it provides transparency, accountability, and systematic improvement.

---

📖 Documentation

Complete documentation available at agenticgovernance.digital:

• Introduction - Framework overview and philosophy
• Core Concepts - Deep dive into each service
• Implementation Guide - Integration instructions
• Case Studies - Real-world failure modes prevented
• API Reference - Complete technical documentation

This repository focuses on open source code and implementation. For conceptual documentation, research background, and interactive demos, please visit the website.

---

🧪 Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:security

# Watch mode
npm run test:watch

Test Coverage: 238 tests across core framework services

---

🏗️ Architecture

tractatus/
├── src/
│   ├── services/              # Core framework services
│   │   ├── InstructionPersistenceClassifier.service.js
│   │   ├── CrossReferenceValidator.service.js
│   │   ├── BoundaryEnforcer.service.js
│   │   ├── ContextPressureMonitor.service.js
│   │   ├── MetacognitiveVerifier.service.js
│   │   └── PluralisticDeliberationOrchestrator.service.js
│   ├── models/                # Database models (MongoDB)
│   ├── routes/                # API routes
│   └── middleware/            # Framework middleware
├── tests/                     # Test suites
│   ├── unit/                  # Service unit tests
│   └── integration/           # Integration tests
├── scripts/                   # Framework utilities
│   ├── framework-components/  # Proactive scanners
│   └── hook-validators/       # Pre-action validators
├── docs/                      # Development documentation
└── public/                    # Website frontend

---

🌐 Multi-Project Ecosystem & Platform-Admin Hub

Tractatus Framework operates in a hub-and-spoke architecture across multiple production projects:

Projects Using Tractatus

1. Tractatus (Framework Authority)

• Port: 9001 (reserved)
• Role: Framework development and governance specification
• Rules: 94 instructions (68 active, 26 inactive)
• Schema: v3.0 (migrated 2025-11-02)
• Scope: Framework concepts, schemas, core governance principles

2. Family-History Platform (Production Implementation)

• Port: 7000 (dev), 8000 (prod)
• Role: Multi-tenant family history platform with Tractatus governance
• Rules: 42 active instructions
• Schema: v3.0 (migrated 2025-11-02)
• Scope: Implementation-specific rules, security, privacy, multi-tenancy

3. Platform-Admin (Coordination Hub)

• Port: 9000
• Role: Aggregates documentation and governance analytics across all projects
• Rules: 8 meta-governance instructions
• Schema: v2.1
• Scope: Cross-project coordination, NOT authoritative source

4. Additional Projects (Planned)

• Passport-Consolidated: Port 9100
• Sydigital: Port 9200

Hub-and-Spoke Architecture

                   ┌─────────────────────────┐
                   │   Platform-Admin Hub    │
                   │   Port 9000             │
                   │   - Documentation       │
                   │   - Analytics           │
                   │   - Observation Only    │
                   └───────────┬─────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            │                  │                  │
            ▼                  ▼                  ▼
    ┌───────────────┐  ┌──────────────┐  ┌──────────────┐
    │   Tractatus   │  │  Family-     │  │  Passport-   │
    │   (Authority) │  │  History     │  │  Consol.     │
    │   50 rules    │  │  42 rules    │  │  (Planned)   │
    └───────────────┘  └──────────────┘  └──────────────┘

Key Principles

Zero Required Coupling: Each project functions perfectly without hub availability. Hub provides observation and reporting only.

Documentation Ownership: Following the Documentation Ownership Policy:

• Tractatus: Owns ALL framework concepts, schemas, governance principles (authoritative)
• Project Repos: Own implementation-specific details
• Platform-Admin: Aggregates and coordinates, NEVER authoritative

Single Source of Truth: Each concept has exactly ONE authoritative location. All other references LINK to source, never duplicate.

Platform-Admin Services

The hub provides two primary services:

1. Documentation Aggregator

• Indexes 1,259+ documents across all projects
• Full-text search across ecosystem
• Real-time index updates
• Dashboard: http://localhost:9000/dashboards/documentation-hub.html

2. Governance Analytics

• Analyzes 138+ rules across projects
• Coverage metrics by category, quadrant, persistence
• Security classification distribution
• Dashboard: http://localhost:9000/dashboards/governance-analytics.html

Port Management

Centralized port allocation prevents conflicts:

• Registry: ~/PORT_ALLOCATION_REGISTRY.md
• Check Script: ~/scripts/check-ports.sh
• Convenience Commands: ~/.bash_aliases_projects (40+ aliases)
• Governance Rule: inst_fh_framework_005 enforces port checking at session start

Governance Coordination

Schema Standardization: All projects migrated to Schema v3.0 (November 2025)

• Unified field structure across ecosystem
• Security classification system (PUBLIC → SECRET)
• Verification requirements (MANDATORY → BEST_EFFORT)
• Backward-compatible with v2.x implementations

Authorization System (Planned): Vault-based authorization architecture

• TIER_0 (single developer, 2FA) through TIER_4 (multinational, board approval)
• Time-limited tokens for governance rule modifications
• See: GOVERNANCE_AUTHORIZATION_SYSTEM_PLAN.md (INTERNAL classification)

Getting Started with Multi-Project Setup

# 1. Check port allocations before starting work
~/scripts/check-ports.sh

# 2. Start the platform-admin hub
sudo systemctl start platform-admin
curl http://localhost:9000/health

# 3. Start your project (e.g., family-history)
sudo systemctl start family-history-dev
curl http://localhost:7000/health

# 4. Access dashboards
open http://localhost:9000/dashboards/documentation-hub.html
open http://localhost:9000/dashboards/governance-analytics.html

Note: Platform-admin hub is optional. Each project functions independently with full governance enforcement.

---

⚠️ Current Research Challenges

Rule Proliferation & Scalability

Status: Active research area | Priority: High

As the framework learns from failures, instruction count grows organically. Current metrics:

• Initial deployment: ~6 core instructions
• Current state: 52 active instructions
• Growth pattern: Increases with each incident response

Open questions:

• At what point does rule proliferation reduce framework effectiveness?
• How do we balance comprehensiveness with cognitive/context load?
• Can machine learning optimize rule selection without undermining transparency?

Mitigation strategies under investigation:

• Instruction consolidation and hierarchical organization
• Rule prioritization algorithms
• Context-aware selective loading
• Periodic rule review and deprecation processes

Research transparency: We're documenting this limitation openly because architectural honesty is core to the framework's integrity.

---

🤝 Contributing

We welcome contributions in several areas:

Research Contributions

• Formal verification of safety properties
• Extensions to new domains (robotics, autonomous systems)
• Theoretical foundations and proofs

Implementation Contributions

• Ports to other languages (Python, Rust, Go)
• Integration with other frameworks
• Performance optimizations

Documentation Contributions

• Tutorials and implementation guides
• Case studies from real deployments
• Translations

See CONTRIBUTING.md for guidelines.

---

📊 Project Status

Current Phase: Research Implementation (October 2025)

✅ All 6 core services implemented ✅ 238 tests passing (unit + integration) ✅ MongoDB persistence operational ✅ Deployed at agenticgovernance.digital ✅ Framework governing its own development (dogfooding)

Next Milestones:

• Multi-language ports (Python, TypeScript)
• Enterprise integration guides
• Formal verification research
• Community case study collection

---

📜 License

Copyright 2025 John Stroh

Licensed under the Apache License, Version 2.0. See LICENSE for full terms.

The Tractatus Framework is open source and free to use, modify, and distribute with attribution.

---

🌐 Links

• Website: agenticgovernance.digital
• Documentation: agenticgovernance.digital/docs
• Interactive Demo: 27027 Incident
• GitHub: AgenticGovernance/tractatus-framework

---

📧 Contact

• Email: john.stroh.nz@pm.me
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🙏 Acknowledgments

This framework stands on the shoulders of:

• Ludwig Wittgenstein - Philosophical foundations from Tractatus Logico-Philosophicus
• March & Simon - Organizational theory and decision-making frameworks
• Isaiah Berlin & Ruth Chang - Value pluralism and incommensurability theory
• Anthropic - Claude AI system for validation and development support
• Open Source Community - Tools, libraries, and collaborative development

---

📖 Philosophy

"Whereof one cannot speak, thereof one must be silent." — Ludwig Wittgenstein

Applied to AI safety:

"Whereof the AI cannot safely decide, thereof it must request human judgment."

Tractatus recognizes that some decisions cannot be systematized without value judgments. Rather than pretend AI can make these decisions "correctly," we build systems that structurally defer to human judgment in appropriate domains.

This isn't a limitation—it's architectural integrity.

---

👥 Development Attribution

This framework represents collaborative human-AI development:

• Conceptual design, governance architecture, and quality oversight: John Stroh
• Implementation, documentation, and iterative refinement: Developed through extended collaboration with Claude (Anthropic)
• Testing and validation: Tested across ~500 Claude Code sessions over 6 months

This attribution reflects the reality of modern AI-assisted development while maintaining clear legal copyright (John Stroh) and transparent acknowledgment of AI's substantial role in implementation.

---

Tractatus Framework | Documentation | Apache 2.0 License