How It Works
Pattern Override Challenge
AI systems operating across extended interactions may not maintain instruction consistency as context evolves. Instructions given early can be deprioritized or reinterpreted.
External Architecture Approach
Tractatus services run external to the AI model, providing boundary validation, instruction classification, and audit logging through architectural separation.
Request Flow with Governance
Example: AI decision flow with boundary enforcementβfrom user request through governance validation to human approval.
System Architecture
Six Core Services
System Architecture
High-level overview showing how the 6 governance services integrate with your application and data layer.
Hook Architecture: The Credibility Layer
Tractatus governance is not voluntary compliance. PreToolUse hooks enforce boundaries before AI actions execute, making circumvention architecturally impossible.
The Voluntary Compliance Problem
Traditional AI safety relies on the AI system "choosing" to follow rules embedded in training data or system prompts. These approaches assume the AI will maintain alignment regardless of context pressure or capability.
Tractatus addresses this through architectural enforcement: governance runs in a separate process that the AI cannot access, modify, or bypass.
PreToolUse Hook Execution Flow
Before any file edit, write, or bash command executes, the hook intercepts the action and runs validation checks. Only if ALL checks pass (exit code 0) does the AI action proceed.
Real Enforcement Examples
π« GitHub URL Protection (inst_084)
AI attempted to change GitHub repository URL from tractatus-framework (public)
to tractatus (private).
Reason: Would expose private repo structure
Hook: validate-file-edit.js line 448-505
π« CSP Violation (inst_008)
AI attempted to add inline style attribute to HTML element.
Pattern:
style="margin: 0 auto"
Hook: validate-file-write.js line 68-149
π« Governance File Protection (inst_027)
AI attempted direct edit of instruction-history.json.
Use: scripts/add-instruction.js instead
Hook: framework-audit-hook.js line 204-209
β Human Approval Required (BoundaryEnforcer)
AI action touches values-sensitive file (privacy policy).
Requires: Explicit human approval
Hook: validate-file-write.js line 239-262
Technical Implementation
π Process Separation
Hooks execute in a separate Node.js process (child_process.spawn) with their own memory space. The AI agent cannot access, modify, or terminate the validation process.
// .claude/hooks.json
{
"PreToolUse:Edit": {
"command": "node",
"args": ["scripts/hook-validators/validate-file-edit.js"]
},
"PreToolUse:Write": {
"command": "node",
"args": ["scripts/hook-validators/validate-file-write.js"]
}
}
βοΈ Exit Code Enforcement
Hook validators return exit codes that Claude Code's architecture enforces:
0= PASS β Tool executes2= HARD BLOCK β Tool execution halted, error shown to user
// validate-file-edit.js (line 373-382)
const githubUrlCheck = checkGitHubURLProtection();
if (!githubUrlCheck.passed) {
error(githubUrlCheck.reason);
console.error(githubUrlCheck.output);
logMetrics('blocked', githubUrlCheck.reason);
process.exit(2); // β HARD BLOCK: Tool cannot execute
}
π Audit Trail
Every hook execution is logged to .claude/metrics/hooks-metrics.json
with timestamp, file, result, and reason. Blocks are separately tracked for analysis.
{
"hook": "validate-file-edit",
"timestamp": "2025-10-26T22:02:15.XXX",
"file": "/public/implementer.html",
"result": "blocked",
"reason": "inst_084: GitHub repository name change detected"
}
Why Architectural Enforcement Matters
This is the fundamental difference between Tractatus and traditional AI safety approaches:
β Voluntary Compliance
- AI "chooses" to follow rules
- Can drift under context pressure
- Pattern recognition may override instructions
- No verification before execution
β Architectural Enforcement
- Hook intercepts before execution
- Separate process, cannot be accessed
- Exit codes enforced by runtime
- Audit trail of all decisions
Deployment Architecture
Technology Stack
Production Deployment
Comprehensive deployment guide covering local development, production server configuration, Docker containerization, cloud deployment patterns (AWS, GCP, Kubernetes), database management, monitoring, and security best practices.
π¦ Covered in Guide:
- Local development setup
- Production server configuration
- Docker and Docker Compose
- Cloud deployment (AWS/GCP)
π§ Also Includes:
- Kubernetes manifests
- Database backup and migration
- SSL/TLS configuration
- Monitoring and logging
Core Services
BoundaryEnforcer
Implements Tractatus 12.1-12.7: AI cannot make values decisions without human approval.
- VALUES (12.1) - Ethics, privacy, principles
- INNOVATION (12.2) - Architectural decisions
- WISDOM (12.3) - Strategic judgment
- PURPOSE (12.4) - Goal definition
const { checkBoundary } = require('./services/BoundaryEnforcer')
const result = await checkBoundary(decision)
// Returns: { allowed: false, requires_human: true }
InstructionPersistenceClassifier
Classifies instructions by quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM) and persistence level (HIGH/MEDIUM/LOW).
- Quadrant (STRATEGIC/OPERATIONAL/TACTICAL/SYSTEM)
- Persistence (HIGH/MEDIUM/LOW)
- Temporal scope (PROJECT/SESSION/TASK)
- Explicitness score (0.0-1.0)
const { classify } = require('./services/InstructionPersistenceClassifier')
const result = await classify(instruction)
// Returns: { quadrant, persistence, temporal_scope, explicitness }
CrossReferenceValidator
Validates AI actions against stored instructions to prevent pattern recognition overrides.
- Checks action against HIGH persistence instructions
- Detects conflicts (pattern vs explicit instruction)
- Provides correct parameters when rejected
const { validate } = require('./services/CrossReferenceValidator')
const result = await validate(action, instructions)
// Returns: { status: 'REJECTED', conflicts, correct_parameters }
ContextPressureMonitor
Monitors token usage and context pressure, triggering safety protocols at thresholds.
- NORMAL (0-50%) - Full operation
- ELEVATED (50-75%) - Increase verification
- HIGH (75-90%) - Reduce complexity
- CRITICAL (90%+) - Suggest handoff
const { analyzePressure } = require('./services/ContextPressureMonitor')
const result = await analyzePressure(tokens, messages)
// Returns: { level: 'HIGH', score: 82, shouldReduce: true }
MetacognitiveVerifier
Verifies action reasoning and confidence, requiring confirmation for low-confidence actions.
- Confidence scoring (0.0-1.0)
- Selective mode (HIGH persistence only)
- Requires confirmation if confidence < 0.7
const { verify } = require('./services/MetacognitiveVerifier')
const result = await verify(action, reasoning)
// Returns: { confidence: 0.65, requires_confirmation: true }
PluralisticDeliberationOrchestrator
Manages multi-stakeholder deliberation ensuring value pluralism in decisions.
- Stakeholder perspective tracking
- Value conflict detection
- Deliberation session management
- Precedent storage
const { orchestrate } = require('./services/PluralisticDeliberationOrchestrator')
const result = await orchestrate(decision, stakeholders)
// Returns: { decision, perspectives, conflicts_identified }
π Source Code
Code patterns and examples are available in the GitHub repository.
API Reference
BoundaryEnforcer.checkBoundary()
const { checkBoundary } = require('./src/services/BoundaryEnforcer.service')
// Check if decision crosses Tractatus boundary
const decision = {
domain: 'values',
description: 'Change privacy policy to enable analytics',
context: { /* ... */ }
}
const result = await checkBoundary(decision)
// Returns:
{
allowed: false, // AI cannot proceed
requires_human: true, // Human decision required
boundary: "12.1", // Tractatus boundary violated
principle: "Values cannot be automated, only verified",
reason: "Decision involves values domain",
ai_can_provide: [ // What AI CAN do
"Analyze privacy implications",
"List alternative approaches",
"Document tradeoffs"
]
}
InstructionPersistenceClassifier.classify()
const { classify } = require('./src/services/InstructionPersistenceClassifier.service')
const instruction = "Always use MongoDB on port 27017"
const result = await classify(instruction, context)
// Returns:
{
quadrant: 'SYSTEM', // Decision domain
persistence: 'HIGH', // How long to remember
temporal_scope: 'PROJECT', // Scope of applicability
verification_required: 'MANDATORY', // Verification level
explicitness: 0.85, // Confidence score
parameters: {
port: "27017",
database: "mongodb",
service: "mongodb"
}
}
Persistence: HIGH (override all), MEDIUM (session-scoped), LOW (can be superseded)
CrossReferenceValidator.validate()
const { validate } = require('./src/services/CrossReferenceValidator.service')
// User instructed: "Use port 27027"
// AI attempting: port 27017 (pattern recognition)
const action = {
type: 'db_config',
parameters: { port: 27017 }
}
const instructions = await getStoredInstructions() // From MongoDB
const result = await validate(action, instructions)
// Returns (CONFLICT):
{
status: 'REJECTED',
conflicts: [
{
instruction_id: 'inst_042',
instruction: 'Use MongoDB port 27027',
persistence: 'HIGH',
conflict: 'Proposed port 27017 conflicts with instruction port 27027'
}
],
correct_parameters: {
port: 27027 // Use this instead
}
}
ContextPressureMonitor.analyzePressure()
const { analyzePressure } = require('./src/services/ContextPressureMonitor.service')
const pressure = await analyzePressure({
currentTokens: 150000,
maxTokens: 200000,
messageCount: 45,
errorCount: 2
})
// Returns:
{
level: 'HIGH', // NORMAL|ELEVATED|HIGH|CRITICAL
score: 75, // 0-100 percentage
shouldReduce: true, // Reduce complexity
recommendations: [
'Consider handoff to new session',
'Reduce verbose explanations',
'Increase verification for remaining actions'
],
thresholds: {
tokens: 75, // 75% of max
messages: 64, // 45/70 messages
errors: 40 // 2 errors
}
}
Integration Examples
Express Middleware Integration
const express = require('express')
const { BoundaryEnforcer } = require('./services')
const app = express()
// Add boundary checking middleware
app.use(async (req, res, next) => {
if (req.body.decision) {
const check = await BoundaryEnforcer.checkBoundary(
req.body.decision
)
if (!check.allowed) {
return res.status(403).json({
error: 'Boundary violation',
reason: check.reason,
alternatives: check.ai_can_provide
})
}
}
next()
})
Instruction Validation
const {
InstructionPersistenceClassifier,
CrossReferenceValidator
} = require('./services')
// Classify and store user instruction
const classification = await
InstructionPersistenceClassifier.classify(
userInstruction
)
if (classification.explicitness >= 0.6) {
await storeInstruction(classification)
}
// Validate AI action before execution
const validation = await
CrossReferenceValidator.validate(
proposedAction,
await getStoredInstructions()
)
if (validation.status === 'REJECTED') {
console.error(validation.conflicts)
useCorrectParameters(
validation.correct_parameters
)
}
MongoDB Data Models
GovernanceRule
{
id: "inst_001",
text: "Use MongoDB port 27017",
quadrant: "SYSTEM",
persistence: "HIGH",
temporal_scope: "PROJECT",
explicitness: 0.85,
parameters: { port: "27017" },
active: true,
timestamp: "2025-10-21T10:00:00Z"
}
AuditLog
{
action: "boundary_check",
result: "REJECTED",
boundary: "12.1",
decision: { /* ... */ },
timestamp: "2025-10-21T11:30:00Z",
session_id: "2025-10-21-001"
}
Deployment
Requirements
-
β’
Node.js: v18.0.0+ (v20+ recommended)
-
β’
MongoDB: v7.0+ (for instruction persistence)
-
β’
Memory: 2GB+ recommended
Installation
# Clone the framework repository
git clone https://github.com/AgenticGovernance/tractatus-framework.git
cd tractatus-framework
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI
# Initialize MongoDB indexes
node scripts/init-db.js
# Start the server
npm start
π Full Documentation
Complete deployment patterns and examples available in the GitHub repository.
Integration Patterns
Common architectural patterns for integrating Tractatus into existing systems.
Middleware Integration
Insert governance checks as middleware in your request pipeline. Suitable for API-based AI systems.
Use Case: REST APIs, Express.js applications
app.use(governanceMiddleware({
services: ['BoundaryEnforcer', 'CrossReferenceValidator'],
mode: 'strict',
auditAll: true
}))
Event-Driven Governance
Trigger governance checks via events. Suitable for async workflows and microservices.
Use Case: Message queues, event buses, async processing
eventBus.on('ai:decision', async (event) => {
const result = await checkBoundary(event.decision)
if (!result.allowed) {
await requestHumanApproval(event, result)
}
})
Pre/Post-Action Hooks
Validate actions before and after execution. Current production pattern for Claude Code.
Use Case: LLM tool use, autonomous agents
hooks: {
PreToolUse: governanceCheck,
PostToolUse: auditLog,
SessionStart: loadInstructions,
SessionEnd: cleanup
}
Sidecar Governance Service
Deploy governance as a separate service. Suitable for multi-LLM or polyglot environments.
Use Case: Kubernetes, containerized deployments
// AI Service makes HTTP call
const govResponse = await fetch(
'http://governance-sidecar:8080/check',
{ method: 'POST', body: JSON.stringify(decision) }
)
Performance Optimization with Agent Lightning
Integrate Microsoft's Agent Lightning for reinforcement learning-based optimization while maintaining full governance coverage.
ποΈ Two-Layer Architecture
Tractatus governance sits above Agent Lightning optimization, creating a separation of concerns: governance enforces boundaries, AL optimizes performance within those boundaries.
Layer 1: Governance (Tractatus)
- β BoundaryEnforcer: Classifies decisions as safe/unsafe
- β CrossReferenceValidator: Validates against constraints
- β PluralisticDeliberator: Manages stakeholder input
- β PressureMonitor: Detects manipulation attempts
Layer 2: Performance (Agent Lightning)
- β‘ Reinforcement Learning: Optimizes response quality
- β‘ Human Feedback: Learns from user corrections
- β‘ Training Loops: Continuous improvement over time
- β‘ Cost Efficiency: Maintains performance with lower compute
Key Insight: Governance runs before Agent Lightning optimization. AL never sees unsafe decisions - they're blocked at the governance layer.
π¦ Implementation Example
Use the GovernedAgentLightning wrapper to combine governance + performance optimization:
from tractatus_agent_lightning import GovernedAgentLightning
from agentlightning import AgentLightning
# Initialize governed agent
agent = GovernedAgentLightning(
base_agent=AgentLightning(agent_id="customer-support-bot"),
governance_config={
"services": ["BoundaryEnforcer", "CrossReferenceValidator"],
"mode": "strict", # Block any governance violations
"audit_all": True # Log all decisions
},
mongodb_uri="mongodb://localhost:27017/governance"
)
# Agent Lightning trains on feedback, Tractatus validates boundaries
for user_message in conversation:
# Governance check happens first
response = agent.respond(user_message)
# User feedback feeds Agent Lightning optimization
if user_corrected:
agent.update_from_feedback(
original_response=response,
corrected_response=user_correction,
rating=user_rating
)
# Governance audit logs the training update
π Preliminary Findings: Demo 2 Results
Small-Scale Validation Only
These results are from Demo 2: 5 training rounds, single agent, simulated environment. Not validated at production scale. Consider this preliminary evidence requiring further research.
Early evidence from small-scale demo suggests Agent Lightning can maintain near-baseline performance while reducing compute requirements, without compromising governance coverage.
| Metric | Baseline (No AL) |
Governed + AL (Tractatus + AL) |
Delta |
|---|---|---|---|
| User Engagement | 94% | 89% | -5% |
| Governance Coverage | 100% | 100% | 0% |
| Constraint Violations | 0 | 0 | 0 |
| Audit Trail Completeness | 100% | 100% | 0% |
Interpretation for Implementers:
- β Governance Preserved: 100% coverage maintained - no violations observed across 5 rounds
- β Performance Cost: 5% engagement reduction may be acceptable for high-stakes use cases (healthcare, finance, legal)
- ? Open Question: Does performance gap close over more training rounds? Requires longer-term validation.
Critical Limitations
- β’ Scale: Only 5 training rounds - insufficient to claim production readiness
- β’ Environment: Simulated interactions - not tested with real users
- β’ Agent Count: Single agent - multi-agent scenarios untested
- β’ Duration: Short-term only - long-term stability unknown
- β’ Edge Cases: Adversarial inputs and stress testing not performed
β οΈ Do not use these numbers as production validation. Conduct your own testing in your specific context.
π Try the Integration
Download the install pack with Demo 2 (governed agent) and explore the integration yourself. Includes full source code, governance modules, and setup instructions.
Development Roadmap & Collaboration
Tractatus is an active research framework. We welcome collaboration on priority development areas.
π Priority Areas for Development
These initiatives represent high-impact opportunities for framework enhancement. Technical contributors, researchers, and organizations are encouraged to engage.
Multi-LLM Support
Status: Research Phase
Extend governance to GPT-4, Gemini, Llama, and local models. Requires adapting hook architecture to different LLM interfaces.
Language Bindings
Status: Community Interest
Python, Go, and Rust implementations to serve broader developer communities. Core logic is portable; MongoDB integration is universal.
Cloud-Native Deployment
Status: Reference Architectures Needed
Terraform/Helm charts for AWS, Azure, GCP. Include managed MongoDB (Atlas), auto-scaling, and monitoring integration.
Business Intelligence Tools
v1.0 Prototype LiveStatus: Research Validation Phase
Transform governance logs into executive insights: cost avoidance calculator, framework maturity scoring, and team performance analytics. Demonstrates ROI of governance decisions in real-time.
AI Framework Integration
Status: Conceptual
Adapters for LangChain, Semantic Kernel, AutoGPT, and CrewAI. Enable governance for existing agent frameworks.
Enterprise-Scale Performance
Status: Validation Needed
Optimize for 1000+ concurrent AI agents. Requires caching strategies, rule compilation, and distributed audit logging.
Extended Governance Services
Status: Research
Cost monitoring, rate limiting, PII detection, adversarial prompt defense. Domain-specific services for regulated industries.
Get Involved
Tractatus is Apache 2.0 licensed research. We welcome contributions, pilot implementations, and collaborative research partnerships.
π¨βπ» Technical Contributors
Implement features, fix bugs, improve documentation
β Contributing Guideπ¬ Research Partners
Validation studies, academic collaboration, case studies
β research@agenticgovernance.digitalπ’ Organization Pilots
Production deployments, enterprise requirements, feedback loops
β Submit Case StudyWhy Collaborate? Tractatus addresses real gaps in AI safety. Early adopters shape the framework's evolution and gain expertise in structural AI governanceβa differentiating capability as regulatory requirements mature.
Resources
Documentation
Reference Implementation
This website (agenticgovernance.digital) runs on Tractatus governance.
- Services: 22 governance components
- Data Models: 29 MongoDB schemas
- Test Coverage: 35 test suites
- β Collaboration Repository
Support
Questions about implementation or integration?