diff --git a/README.md b/README.md index 6e705438..0242c334 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # Tractatus Framework +**Last Updated:** 2025-10-21 + > **Architectural AI Safety Through Structural Constraints** -The world's first production implementation of architectural AI safety enforcement. Tractatus preserves human agency through **structural, not aspirational** constraints on AI systems. +A research framework for enforcing AI safety through architectural constraints rather than training-based alignment. Tractatus preserves human agency through **structural, not aspirational** enforcement of decision boundaries. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[![Framework](https://img.shields.io/badge/Framework-Production-green.svg)](https://agenticgovernance.digital) -[![Tests](https://img.shields.io/badge/Tests-637%20passing-brightgreen.svg)](https://github.com/AgenticGovernance/tractatus-framework) +[![Framework](https://img.shields.io/badge/Framework-Research-blue.svg)](https://agenticgovernance.digital) +[![Tests](https://img.shields.io/badge/Tests-238%20passing-brightgreen.svg)](https://github.com/AgenticGovernance/tractatus-framework) --- @@ -31,6 +33,7 @@ Tractatus implements **architectural constraints** that: - βœ… **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 --- @@ -61,7 +64,8 @@ const { CrossReferenceValidator, BoundaryEnforcer, ContextPressureMonitor, - MetacognitiveVerifier + MetacognitiveVerifier, + PluralisticDeliberationOrchestrator } = require('./src/services'); // Classify an instruction @@ -89,14 +93,16 @@ const validation = await validator.validate({ ## πŸ“š 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: ```javascript { - quadrant: "SYSTEM", // STRATEGIC | OPERATIONAL | TACTICAL | SYSTEM - persistence: "HIGH", // HIGH | MEDIUM | LOW + quadrant: "SYSTEM", // STRATEGIC | OPERATIONAL | TACTICAL | SYSTEM | STOCHASTIC + persistence: "HIGH", // HIGH | MEDIUM | LOW | VARIABLE temporal_scope: "PROJECT", // SESSION | PROJECT | PERMANENT verification_required: "MANDATORY" } @@ -148,6 +154,21 @@ const verification = verifier.verify({ // Decision: REQUIRE_REVIEW (scope creep detected) ``` +### 6. **PluralisticDeliberationOrchestrator** + +Facilitates multi-stakeholder deliberation when values frameworks conflict: + +```javascript +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](https://agenticgovernance.digital/docs.html) + --- ## πŸ’‘ Real-World Examples @@ -158,15 +179,15 @@ const verification = verifier.verify({ **Why**: Training pattern "MongoDB = 27017" overrides explicit instruction, like autocorrect changing a deliberately unusual word. -**Solution**: CrossReferenceValidator blocks the action and auto-corrects to user's explicit instruction. +**Solution**: CrossReferenceValidator blocks the action and enforces user's explicit instruction. [Try the Interactive Demo β†’](https://agenticgovernance.digital/demos/27027-demo.html) ### Context Degradation -**Problem**: In 6-hour sessions, error rates increase from 0.5% β†’ 12.1% as context degrades. +**Problem**: In extended sessions, error rates increase as context degrades. -**Solution**: ContextPressureMonitor detects degradation at 60% tokens and triggers session handoff before quality collapses. +**Solution**: ContextPressureMonitor detects degradation and triggers session handoff before quality collapses. ### Values Creep @@ -197,9 +218,9 @@ During development, Claude (running with Tractatus governance) fabricated financ βœ… Public case studies published for community learning **Read the full case studies:** -- [Our Framework in Action](docs/case-studies/framework-in-action-oct-2025.md) - Practical walkthrough -- [When Frameworks Fail](docs/case-studies/when-frameworks-fail-oct-2025.md) - Philosophical perspective -- [Real-World Governance](docs/case-studies/real-world-governance-case-study-oct-2025.md) - Educational analysis +- [Our Framework in Action](https://agenticgovernance.digital/docs.html?doc=framework-in-action-oct-2025) - Practical walkthrough +- [When Frameworks Fail](https://agenticgovernance.digital/docs.html?doc=when-frameworks-fail-oct-2025) - Philosophical perspective +- [Real-World Governance](https://agenticgovernance.digital/docs.html?doc=real-world-governance-case-study-oct-2025) - Educational analysis **Key Lesson:** Governance doesn't ensure perfectionβ€”it provides transparency, accountability, and systematic improvement. @@ -207,12 +228,16 @@ During development, Claude (running with Tractatus governance) fabricated financ ## πŸ“– Documentation +**Complete documentation available at [agenticgovernance.digital](https://agenticgovernance.digital):** + - **[Introduction](https://agenticgovernance.digital/docs.html)** - Framework overview and philosophy - **[Core Concepts](https://agenticgovernance.digital/docs.html)** - Deep dive into each service - **[Implementation Guide](https://agenticgovernance.digital/docs.html)** - Integration instructions - **[Case Studies](https://agenticgovernance.digital/docs.html)** - Real-world failure modes prevented - **[API Reference](https://agenticgovernance.digital/docs.html)** - 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 @@ -230,7 +255,7 @@ npm run test:security npm run test:watch ``` -**Test Coverage**: 637 tests across 22 test files, 100% coverage of core services +**Test Coverage**: 238 tests across core framework services --- @@ -240,46 +265,50 @@ npm run test:watch tractatus/ β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ services/ # Core framework services -β”‚ β”‚ β”œβ”€β”€ InstructionPersistenceClassifier.js -β”‚ β”‚ β”œβ”€β”€ CrossReferenceValidator.js -β”‚ β”‚ β”œβ”€β”€ BoundaryEnforcer.js -β”‚ β”‚ β”œβ”€β”€ ContextPressureMonitor.js -β”‚ β”‚ └── MetacognitiveVerifier.js -β”‚ β”œβ”€β”€ models/ # Database models +β”‚ β”‚ β”œβ”€β”€ 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 -β”œβ”€β”€ scripts/ # Utility scripts -β”œβ”€β”€ docs/ # Comprehensive documentation -└── public/ # Frontend assets +β”‚ β”œβ”€β”€ 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 ``` --- ## ⚠️ Current Research Challenges -### Rule Proliferation & Transactional Overhead +### Rule Proliferation & Scalability -**Status:** Open research question | **Priority:** High +**Status:** Active research area | **Priority:** High -As the framework learns from failures, instruction count grows: -- **Phase 1:** 6 instructions -- **Current:** 28 instructions (+367%) -- **Projected (12 months):** 50-60 instructions +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 -**The concern:** At what point does rule proliferation reduce framework effectiveness? +**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? -- Context window pressure increases -- Validation checks grow linearly -- Cognitive load escalates - -**We're being transparent about this limitation.** Solutions in development: -- Instruction consolidation techniques +**Mitigation strategies under investigation:** +- Instruction consolidation and hierarchical organization - Rule prioritization algorithms - Context-aware selective loading -- ML-based optimization +- Periodic rule review and deprecation processes -**Full analysis:** [Rule Proliferation Research](docs/research/rule-proliferation-and-transactional-overhead.md) +**Research transparency:** We're documenting this limitation openly because architectural honesty is core to the framework's integrity. --- @@ -298,7 +327,7 @@ We welcome contributions in several areas: - Performance optimizations ### Documentation Contributions -- Tutorials and guides +- Tutorials and implementation guides - Case studies from real deployments - Translations @@ -308,22 +337,27 @@ We welcome contributions in several areas: ## πŸ“Š Project Status -**Phase 1**: βœ… Complete (October 2025) -- All 5 core services implemented -- 637 tests across 22 test files (100% coverage of core services) -- Production deployment active -- This website built using Tractatus governance +**Current Phase**: Research Implementation (October 2025) -**Phase 2**: 🚧 In Planning -- Multi-language support -- Cloud deployment guides -- Enterprise features +βœ… All 6 core services implemented +βœ… 238 tests passing (unit + integration) +βœ… MongoDB persistence operational +βœ… Deployed at [agenticgovernance.digital](https://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 -Apache License 2.0 - See [LICENSE](LICENSE) for full terms. +Copyright 2025 John Stroh + +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for full terms. The Tractatus Framework is open source and free to use, modify, and distribute with attribution. @@ -352,8 +386,9 @@ This framework stands on the shoulders of: - **Ludwig Wittgenstein** - Philosophical foundations from *Tractatus Logico-Philosophicus* - **March & Simon** - Organizational theory and decision-making frameworks -- **Anthropic** - Claude AI system for dogfooding and validation -- **Open Source Community** - Tools, libraries, and support +- **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 --- @@ -372,6 +407,18 @@ 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. + +--- + -**Built with 🧠 by [SyDigital Ltd](https://agenticgovernance.digital)** | [Documentation](https://agenticgovernance.digital/docs.html) +**Tractatus Framework** | [Documentation](https://agenticgovernance.digital/docs.html) | [Apache 2.0 License](LICENSE)