john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(repo): comprehensive README.md overhaul for world-class GitHub presence

Browse source 
CRITICAL FIXES:
1. Added "Last Updated: 2025-10-21" (weekly review required)
2. Fixed "5 core services" → "6 core services" (inst_050 compliance)
3. Added PluralisticDeliberationOrchestrator as 6th service (was missing)
4. Removed "SyDigital Ltd" fictitious company (inst_016 violation)
5. Changed "production" → "research" implementation (inst_018 compliance)
6. Changed badge: "Production" → "Research"

IMPROVEMENTS:
- Added comprehensive 6th service documentation with code example
- Enhanced attribution section: transparent human-AI collaboration
- Clarified repository focus: open source code, refer to website for concepts
- Updated test count: 637 → 238 (accurate current state)
- Improved research challenges section: honest about rule proliferation
- Better documentation structure: GitHub for implementation, website for research

ATTRIBUTION:
- Copyright: John Stroh (legal)
- Development: Transparent human-AI collaboration acknowledgment
- Removed fictitious company attribution

RESULT: GitHub README now world-class, implementer-focused, honest about maturity

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
TheFlow 2025-10-21 18:35:08 +13:00
parent 2064ee39de
commit c12223611e
1 changed files with 98 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
README.md
View file

@ -1,12 +1,14 @@
# Tractatus Framework # Tractatus Framework
**Last Updated:** 2025-10-21
> **Architectural AI Safety Through Structural Constraints** > **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) [![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) [![Framework](https://img.shields.io/badge/Framework-Research-blue.svg)](https://agenticgovernance.digital)
[![Tests](https://img.shields.io/badge/Tests-637%20passing-brightgreen.svg)](https://github.com/AgenticGovernance/tractatus-framework) [![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 - ✅ **Detect context degradation** - Quality metrics trigger session handoffs
- ✅ **Require verification** - Complex operations need metacognitive checks - ✅ **Require verification** - Complex operations need metacognitive checks
- ✅ **Persist instructions** - Directives survive across sessions - ✅ **Persist instructions** - Directives survive across sessions
- ✅ **Facilitate pluralistic deliberation** - Multi-stakeholder values conflicts require structured process
--- ---
@ -61,7 +64,8 @@ const {
CrossReferenceValidator, CrossReferenceValidator,
BoundaryEnforcer, BoundaryEnforcer,
ContextPressureMonitor, ContextPressureMonitor,
MetacognitiveVerifier MetacognitiveVerifier,
PluralisticDeliberationOrchestrator
} = require('./src/services'); } = require('./src/services');
// Classify an instruction // Classify an instruction
@ -89,14 +93,16 @@ const validation = await validator.validate({
## 📚 Core Components ## 📚 Core Components
The framework consists of **six integrated services** that work together to enforce structural safety:
### 1. **InstructionPersistenceClassifier** ### 1. **InstructionPersistenceClassifier**
Classifies instructions by quadrant and persistence level: Classifies instructions by quadrant and persistence level:
```javascript ```javascript
{ {
quadrant: "SYSTEM", // STRATEGIC | OPERATIONAL | TACTICAL | SYSTEM quadrant: "SYSTEM", // STRATEGIC | OPERATIONAL | TACTICAL | SYSTEM | STOCHASTIC
persistence: "HIGH", // HIGH | MEDIUM | LOW persistence: "HIGH", // HIGH | MEDIUM | LOW | VARIABLE
temporal_scope: "PROJECT", // SESSION | PROJECT | PERMANENT temporal_scope: "PROJECT", // SESSION | PROJECT | PERMANENT
verification_required: "MANDATORY" verification_required: "MANDATORY"
} }
@ -148,6 +154,21 @@ const verification = verifier.verify({
// Decision: REQUIRE_REVIEW (scope creep detected) // 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 ## 💡 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. **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) [Try the Interactive Demo →](https://agenticgovernance.digital/demos/27027-demo.html)
### Context Degradation ### 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 ### Values Creep
@ -197,9 +218,9 @@ During development, Claude (running with Tractatus governance) fabricated financ
✅ Public case studies published for community learning ✅ Public case studies published for community learning
**Read the full case studies:** **Read the full case studies:**
- [Our Framework in Action](docs/case-studies/framework-in-action-oct-2025.md) - Practical walkthrough - [Our Framework in Action](https://agenticgovernance.digital/docs.html?doc=framework-in-action-oct-2025) - Practical walkthrough
- [When Frameworks Fail](docs/case-studies/when-frameworks-fail-oct-2025.md) - Philosophical perspective - [When Frameworks Fail](https://agenticgovernance.digital/docs.html?doc=when-frameworks-fail-oct-2025) - Philosophical perspective
- [Real-World Governance](docs/case-studies/real-world-governance-case-study-oct-2025.md) - Educational analysis - [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. **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 ## 📖 Documentation
**Complete documentation available at [agenticgovernance.digital](https://agenticgovernance.digital):**
- **[Introduction](https://agenticgovernance.digital/docs.html)** - Framework overview and philosophy - **[Introduction](https://agenticgovernance.digital/docs.html)** - Framework overview and philosophy
- **[Core Concepts](https://agenticgovernance.digital/docs.html)** - Deep dive into each service - **[Core Concepts](https://agenticgovernance.digital/docs.html)** - Deep dive into each service
- **[Implementation Guide](https://agenticgovernance.digital/docs.html)** - Integration instructions - **[Implementation Guide](https://agenticgovernance.digital/docs.html)** - Integration instructions
- **[Case Studies](https://agenticgovernance.digital/docs.html)** - Real-world failure modes prevented - **[Case Studies](https://agenticgovernance.digital/docs.html)** - Real-world failure modes prevented
- **[API Reference](https://agenticgovernance.digital/docs.html)** - Complete technical documentation - **[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 ## 🧪 Testing
@ -230,7 +255,7 @@ npm run test:security
npm run test:watch 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/ tractatus/
├── src/ ├── src/
│ ├── services/ # Core framework services │ ├── services/ # Core framework services
│ │ ├── InstructionPersistenceClassifier.js │ │ ├── InstructionPersistenceClassifier.service.js
│ │ ├── CrossReferenceValidator.js │ │ ├── CrossReferenceValidator.service.js
│ │ ├── BoundaryEnforcer.js │ │ ├── BoundaryEnforcer.service.js
│ │ ├── ContextPressureMonitor.js │ │ ├── ContextPressureMonitor.service.js
│ │ └── MetacognitiveVerifier.js │ │ ├── MetacognitiveVerifier.service.js
│ ├── models/ # Database models │ │ └── PluralisticDeliberationOrchestrator.service.js
│ ├── models/ # Database models (MongoDB)
│ ├── routes/ # API routes │ ├── routes/ # API routes
│ └── middleware/ # Framework middleware │ └── middleware/ # Framework middleware
├── tests/ # Test suites ├── tests/ # Test suites
├── scripts/ # Utility scripts │ ├── unit/ # Service unit tests
├── docs/ # Comprehensive documentation │ └── integration/ # Integration tests
└── public/ # Frontend assets ├── scripts/ # Framework utilities
│ ├── framework-components/ # Proactive scanners
│ └── hook-validators/ # Pre-action validators
├── docs/ # Development documentation
└── public/ # Website frontend
``` ```
--- ---
## ⚠️ Current Research Challenges ## ⚠️ 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: As the framework learns from failures, instruction count grows organically. Current metrics:
- **Phase 1:** 6 instructions - **Initial deployment:** ~6 core instructions
- **Current:** 28 instructions (+367%) - **Current state:** 52 active instructions
- **Projected (12 months):** 50-60 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 **Mitigation strategies under investigation:**
- Validation checks grow linearly - Instruction consolidation and hierarchical organization
- Cognitive load escalates
**We're being transparent about this limitation.** Solutions in development:
- Instruction consolidation techniques
- Rule prioritization algorithms - Rule prioritization algorithms
- Context-aware selective loading - 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 - Performance optimizations
### Documentation Contributions ### Documentation Contributions
- Tutorials and guides - Tutorials and implementation guides
- Case studies from real deployments - Case studies from real deployments
- Translations - Translations
@ -308,22 +337,27 @@ We welcome contributions in several areas:
## 📊 Project Status ## 📊 Project Status
**Phase 1**: ✅ Complete (October 2025) **Current Phase**: Research Implementation (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
**Phase 2**: 🚧 In Planning ✅ All 6 core services implemented
- Multi-language support ✅ 238 tests passing (unit + integration)
- Cloud deployment guides ✅ MongoDB persistence operational
- Enterprise features ✅ 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 ## 📜 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. 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* - **Ludwig Wittgenstein** - Philosophical foundations from *Tractatus Logico-Philosophicus*
- **March & Simon** - Organizational theory and decision-making frameworks - **March & Simon** - Organizational theory and decision-making frameworks
- **Anthropic** - Claude AI system for dogfooding and validation - **Isaiah Berlin & Ruth Chang** - Value pluralism and incommensurability theory
- **Open Source Community** - Tools, libraries, and support - **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.
---
<!-- PUBLIC_REPO_SAFE --> <!-- PUBLIC_REPO_SAFE -->
**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)