Start here
Curated framework documentation for implementation:
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 source code repository URL from tractatus-framework (public)
to tractatus (private).
Reason: Would expose private repo structure
Hook: scripts/hook-validators/validate-file-edit.js
π« CSP Violation (inst_008)
AI attempted to add inline style attribute to HTML element.
Pattern:
style="margin: 0 auto"
Hook: scripts/hook-validators/validate-file-write.js
π« Governance File Protection (inst_027)
AI attempted direct edit of instruction-history.json.
Use: scripts/add-instruction.js instead
Hook: .claude/hooks/framework-audit-hook.js
β Human Approval Required (BoundaryEnforcer)
AI action touches values-sensitive file (privacy policy).
Requires: Explicit human approval
Hook: scripts/hook-validators/validate-file-write.js
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/settings.json
{
"hooks": {
"PreToolUse": [{
"matcher": "Edit|Write|Bash",
"hooks": [{ "type": "command", "command": "node .claude/hooks/framework-audit-hook.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 β boundary enforcement example
const githubURLCheck = checkGitHubURLProtection(filePath, content);
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/implementation.html",
"result": "blocked",
"reason": "inst_084: source code 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 enforcer = require('./services/BoundaryEnforcer.service')
const result = await enforcer.enforce(action, context)
// Returns: { allowed, decision, action, principle, ... }
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 classifier = require('./services/InstructionPersistenceClassifier.service')
const result = await classifier.classify({ text: instruction, context, source })
// 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 validator = require('./services/CrossReferenceValidator.service')
const result = await validator.validate(action, context)
// Returns: { status: 'REJECTED', conflicts, correct_parameters }
ContextPressureMonitor
Monitors token usage and context pressure, triggering safety protocols at thresholds.
- NORMAL - Full operation
- ELEVATED - Increase verification
- HIGH - Reduce complexity
- CRITICAL / DANGEROUS - Suggest handoff
const monitor = require('./services/ContextPressureMonitor.service')
const result = await monitor.analyzePressure(context)
// Returns: { level: 'HIGH', score, 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 verifier = require('./services/MetacognitiveVerifier.service')
const result = await verifier.verify(action, reasoning, context)
// Returns: { decision, confidence, level, issues, scores, recommendations }
PluralisticDeliberationOrchestrator
Manages multi-stakeholder deliberation to support value pluralism in decisions.
- Stakeholder perspective tracking
- Value conflict detection
- Deliberation session management
- Precedent storage
const orchestrator = require('./services/PluralisticDeliberationOrchestrator.service')
const conflict = await orchestrator.analyzeConflict(decision, context)
const outcome = await orchestrator.facilitateDeliberation(conflict, stakeholders)
π Source Code
Code patterns and examples are available in the source code repository.
API Reference
BoundaryEnforcer.enforce()
const enforcer = require('./src/services/BoundaryEnforcer.service')
// Check if action crosses a Tractatus boundary (12.1-12.7)
const action = {
domain: 'values',
description: 'Change privacy policy to enable analytics',
context: { /* ... */ }
}
const result = await enforcer.enforce(action, context)
// Returns (when boundary crossed):
{
allowed: false, // AI cannot proceed
decision: 'requires_human_approval',
action: 'block',
boundary: "12.1", // Tractatus boundary
principle: "Values cannot be automated, only verified",
reason: "Action involves values domain",
alternatives: [ // What AI CAN do
"Analyze privacy implications",
"List alternative approaches",
"Document tradeoffs"
]
}
InstructionPersistenceClassifier.classify()
const classifier = require('./src/services/InstructionPersistenceClassifier.service')
const result = await classifier.classify({
text: "Always use MongoDB on port 27017",
context,
source: 'user',
timestamp: Date.now()
})
// Returns:
{
quadrant: 'SYSTEM', // Decision domain
persistence: 'HIGH', // How long to remember
temporal_scope: 'PROJECT', // Scope of applicability
verification_required: 'MANDATORY',
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 validator = 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 result = await validator.validate(action, context)
// 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 monitor = require('./src/services/ContextPressureMonitor.service')
const pressure = await monitor.analyzePressure({
currentTokens: 150000,
maxTokens: 200000,
messageCount: 45,
errorCount: 2
})
// Returns:
{
level: 'HIGH', // NORMAL|ELEVATED|HIGH|CRITICAL|DANGEROUS
score: 75, // 0-100 percentage
shouldReduce: true, // Reduce complexity
recommendations: [
'Consider handoff to new session',
'Reduce verbose explanations',
'Increase verification for remaining actions'
]
}
Integration Examples
Express Middleware Integration
const express = require('express')
const enforcer = require('./services/BoundaryEnforcer.service')
const app = express()
// Add boundary checking middleware
app.use(async (req, res, next) => {
if (req.body.action) {
const check = await enforcer.enforce(req.body.action, req.body.context)
if (!check.allowed) {
return res.status(403).json({
error: 'Boundary violation',
reason: check.reason,
alternatives: check.alternatives
})
}
}
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"
}
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 enforcer.enforce(event.action, event.context)
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) }
)
Village AI: Two-Model Sovereign Architecture
Production deployment of Tractatus governance on locally-trained open-source models, demonstrating framework portability beyond Claude.
Two-Model Routing Architecture
Village AI uses a dual-model design where queries are routed based on complexity and governance requirements. Both models run locally with full Tractatus governance in the inference pipeline.
Base model: 14B Qwen2
- β Per product type: Specialised QLoRA fine-tunes for whΔnau, community, family, business, episcopal (governance product type currently uses the whΔnau base for MΔori cultural content)
- β Inference path: Tractatus services run before model invocation; full 6-service pipeline (BoundaryEnforcer through PDO) audit-logs every decision
- β Local hardware: Parameter-efficient QLoRA on consumer-grade GPUs; community-controlled infrastructure throughout
Sovereignty properties
- π Data: Training data and model weights remain on community infrastructure; no cloud dependency for inference
- π Governance: Constraints are architectural, not retroactive compliance β encoded in the inference pipeline, not bolted on
- π Status: Inference governance operational; sovereign training pipeline in progress
Model Routing Logic
// Simplified routing decision
function routeQuery(query, governanceContext) {
const complexity = assessComplexity(query);
const govRequirement = governanceContext.sensitivityLevel;
if (complexity === 'simple' && govRequirement === 'low') {
return { model: 'llama-3.2-3b', pipeline: 'lightweight' };
}
return { model: 'llama-3.1-8b', pipeline: 'full-governance' };
}
Implementation Details
Status: Inference governance operational. Sovereign training pipeline installation in progress. Production deployment at the Village platform validates governance portability across model architectures.
Steering Vectors: Inference-Time Bias Correction
Techniques for correcting model behaviour at inference time without retraining, applicable to QLoRA-fine-tuned models like those in Village AI.
Reference: Steering Vectors and Mechanical Bias in Sovereign AI Systems (STO-RES-0009 v1.1, February 2026)
Key Techniques for Implementers
Contrastive Activation Addition (CAA)
Extract activation differences between contrasting prompts, then add scaled vectors during inference to steer model behaviour toward desired attributes.
Representation Engineering (RepE)
Identify and manipulate internal representations of concepts (honesty, safety, fairness) through probing and directional manipulation of model activations.
FairSteer
Identify bias-critical layers through probing classifiers, then apply targeted corrections at those specific layers rather than globally.
Direct Steering Optimisation (DSO)
Optimise steering vectors using preference datasets (DPO-style), enabling training-free bias correction that learns from human preference data.
Key Distinction: The paper distinguishes between mechanical bias (pre-reasoning, embedded in model weights β addressable by steering vectors) and reasoning bias (deliberative, arising during inference β requiring governance framework approaches like Tractatus).
Taonga Registry: Governed Data Objects for Indigenous Sovereignty
Architectural patterns for treating steering packs and model configurations as governed data objects with provenance tracking and community-controlled access.
Conceptual Architecture β In Peer Review
Based on STO-RES-0010 v0.1 DRAFT, currently in indigenous peer review. Written without Maori co-authorship β presented as a starting point for collaboration. Not ready for production implementation.
Key Architectural Concepts
Steering Packs as Governed Objects
Model configurations, fine-tuning data, and steering vectors are treated as taonga (treasures) with full provenance tracking, access control, and community consent requirements.
Provenance & Withdrawal Rights
Every data object tracks its full lineage. Communities retain the right to withdraw their data and configurations, with architectural enforcement of removal propagation.
Polycentric Governance Integration
Extends PluralisticDeliberationOrchestrator with iwi/community as co-equal governance authorities. Access decisions require multi-party consensus.
CARE Principles Implementation
Architecturally enforces Collective benefit, Authority to control, Responsibility, and Ethics for indigenous data governance within the Tractatus framework.
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
Reference integration code lives at /integrations/agent-lightning.html. The integration pattern: an Agent Lightning training loop feeds proposed actions through the Tractatus services chain (BoundaryEnforcer β CrossReferenceValidator β audit) before any reward signal is recorded; only governance-passing actions are eligible for reward updates.
Preliminary Findings: Demo 2 Results
Demo 2 (single agent, 5 training rounds, simulated environment) suggests governance coverage holds through reinforcement-learning training cycles. Numbers below are from this demo only β see /integrations/agent-lightning.html for context.
| Metric | Baseline (No AL) |
Governed + AL (Tractatus + AL) |
Delta |
|---|---|---|---|
| Governance Coverage | activated | activated | held |
| Constraint Violations | 0 | 0 | 0 |
| Audit Trail Completeness | 100% | 100% | 0% |
Interpretation for Implementers:
- β Governance preserved: Coverage held with no constraint violations observed across the demo run
- ? Open question: Does any observed performance impact close over more training rounds? Requires longer-term validation in the operator's 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
First Deployment LiveStatus: First Non-Claude Deployment Operational
Village AI deploys Tractatus governance on 14B Qwen2 via QLoRA fine-tuning per product type β a non-Claude deployment surface for the framework. Extends governance portability to open-source models with full 6-service pipeline.
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.
Sovereign Training Pipeline
Status: In Progress
Governance-inside-the-training-loop for community-controlled models. Extends Tractatus from inference-time governance to training-time governance, ensuring data sovereignty from fine-tuning through deployment.
Taonga Data Registry
Status: Conceptual / In Peer Review
Governed data objects with provenance tracking, withdrawal rights, and polycentric community governance. Extends PluralisticDeliberationOrchestrator for indigenous data sovereignty.
Get Involved
Tractatus is Apache 2.0 licensed research. We welcome contributions, pilot implementations, and collaborative research partnerships.
Research Partners
Validation studies, academic collaboration, case studies
β research@agenticgovernance.digitalOrganisation 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: Six core governance services + supporting infrastructure
- Data Models: MongoDB-backed audit, instructions, and governance-rule schemas
- Test Coverage: Service-level test suites covering the six core services
- β Collaboration Repository
Support
Questions about implementation or integration?