john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
179 commits 1 branch 0 tags 125 MiB
Commit graph

14 commits

Author SHA1 Message Date
TheFlow
21a6b33fce docs: add value pluralism documentation and research foundations 
- pluralistic-values-research-foundations.md (43KB)
  - Academic grounding for PluralisticDeliberationOrchestrator
  - Deliberative democracy theory
  - Cross-cultural communication principles
  - Value pluralism philosophy
  - References to Berlin, Rawls, Habermas

- value-pluralism-faq.md (17KB)
  - User-facing explanation of foundational pluralism
  - Q&A format for accessibility
  - How Tractatus handles moral disagreement

- pluralistic-values-deliberation-plan-v2.md (42KB)
  - Technical design document
  - Implementation roadmap
  - Service architecture details
  - Integration with existing framework

Migrated to MongoDB for docs.html integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-12 16:36:13 +13:00
TheFlow
ebcd600b30 feat: comprehensive accessibility improvements (WCAG 2.1 AA) 
Achieved 81% error reduction (31 → 6 errors) across 9 pages through systematic
accessibility audit and remediation.

Key improvements:
- Add aria-labels to navigation close buttons (all pages)
- Fix footer text contrast: gray-600 → gray-300 (7 pages)
- Fix button contrast: amber-600 → amber-700, green-600 → green-700
- Fix docs modal empty h2 heading issue
- Fix leader page color contrast (bulk replacement)
- Update audit script: advocate.html → leader.html

Results:
- 7 of 9 pages now fully WCAG 2.1 AA compliant
- Remaining 6 errors likely tool false positives
- All critical accessibility issues resolved

Files modified:
- public/js/components/navbar.js (mobile menu accessibility)
- public/js/components/document-cards.js (modal heading fix)
- public/*.html (footer contrast, button colors)
- public/leader.html (comprehensive color updates)
- scripts/audit-accessibility.js (page list update)

Documentation: docs/accessibility-improvements-2025-10.md

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-12 07:08:40 +13:00
TheFlow
c417f5b7d6 feat: enhance framework services and format architectural documentation 
Framework Service Enhancements:
- ContextPressureMonitor: Enhanced statistics tracking and contextual adjustments
- InstructionPersistenceClassifier: Improved context integration and consistency
- MetacognitiveVerifier: Extended verification capabilities and logging
- All services: 182 unit tests passing

Admin Interface Improvements:
- Blog curation: Enhanced content management and validation
- Audit analytics: Improved analytics dashboard and reporting
- Dashboard: Updated metrics and visualizations

Documentation:
- Architectural overview: Improved markdown formatting for readability
- Added blank lines between sections for better structure
- Fixed table formatting for version history

All tests passing: Framework stable for deployment

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-11 00:50:47 +13:00
TheFlow
88f28e8b83 docs: add comprehensive architectural overview and Phase 5 Session 3 summary 
This commit adds two critical research documentation files summarizing the
Tractatus project from inception through current production-ready status.

## Context
- Phase 5 Sessions 1 & 2 indicated "implementation looks promising"
- Session 3 focused on API Memory observations, MongoDB fixes, and inst_016-018
- Need comprehensive system overview for stakeholders and future research

## New Documentation

### 1. Architectural Overview (v1.0.0)
**File**: docs/research/architectural-overview.md

**Purpose**: Definitive reference for system architecture, research phases, and
current status

**Contents**:
- Executive summary (Phase 5 complete, 223/223 tests passing)
- System architecture (4-layer design with hybrid memory)
- Core services documentation (all 6 services detailed)
- Memory architecture (MongoDB + Anthropic API + filesystem)
- MongoDB schema design (AuditLog, GovernanceRule models)
- Phase 5 detailed progress (Sessions 1-3)
- API Memory observations and behavior patterns
- Instruction persistence system (19 active instructions)
- Test coverage (223 tests, 100% passing)
- Production deployment guide
- Security & privacy architecture
- Performance & scalability analysis
- Future research directions (Phase 6 considerations)
- Lessons learned and architectural insights

**Key Sections**:
- API Memory System Observations (Section 3.4)
- Phase 5 Session 3 detailed summary
- inst_016-018 enforcement implementation
- Production readiness assessment
- Complete command reference appendix

**Format**: Markdown with versioning (v1.0.0), anonymized for public release

### 2. Phase 5 Session 3 Summary
**File**: docs/research/phase-5-session3-summary.md

**Purpose**: Session-specific documentation maintaining consistency with
Sessions 1 & 2 format

**Contents**:
- Executive summary (2.5 hours, all objectives exceeded)
- API Memory system observations (first session with new feature)
- 6 MongoDB persistence fixes (detailed with code examples)
- BoundaryEnforcer inst_016-018 enforcement (MAJOR feature)
- Test results (223/223 passing, 61 BoundaryEnforcer)
- Performance metrics (no degradation)
- Key findings and lessons learned
- Production readiness assessment
- Comparison to Sessions 1 & 2
- Complete command reference appendix

**Key Achievement**: Progressed from "implementation looks promising"
(Sessions 1-2) to "production-ready baseline established" (Session 3)

## API Memory Observations

**First session using Anthropic's new API Memory system**

**Key Findings**:
1. Session continuity detection works (detected continuation from 2025-10-07-001)
2. Instructions NOT loaded automatically by API Memory (loaded via session-init.js)
3. API Memory provides conversation continuity, NOT automatic rule loading
4. Architecture clarified: MongoDB (required) + Anthropic API (optional)
5. Graceful degradation when CLAUDE_API_KEY unavailable
6. Performance: No degradation, framework components remained active

**Implication**: API Memory suitable for conversation continuity but does NOT
replace persistent storage. MongoDB remains required for production.

## Documentation Structure

```
docs/research/
├── architectural-overview.md           # Comprehensive system overview (NEW)
├── phase-5-session1-summary.md        # Existing (67% integration)
├── phase-5-session2-summary.md        # Existing (100% integration)
└── phase-5-session3-summary.md        # NEW (production-ready)
```

**Progression**:
- Session 1: 4/6 services, "looks promising"
- Session 2: 6/6 services, "looks promising"
- Session 3: 6/6 services, "production-ready"

## Version Control

**Architectural Overview**: v1.0.0 (initial comprehensive overview)
**Update Schedule**: Will be versioned and updated over time
**Next Review**: Phase 6 planning (if pursued)

## Statistics

- **Architectural Overview**: ~800 lines, 12 sections, 3 appendices
- **Session 3 Summary**: ~500 lines, 9 sections, 1 appendix
- **Total Documentation**: ~1,300 lines of comprehensive research documentation
- **Format**: Markdown with code examples, tables, ASCII diagrams

## Audience

- Research team and stakeholders
- Future contributors and collaborators
- Production deployment team
- Academic researchers in AI governance
- Public release (anonymized)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-11 00:32:24 +13:00
TheFlow
494daf5123 docs: add Apache 2.0 License to Phase 5 research documents 
Added Apache 2.0 License headers to research documentation for
Anthropic monitoring compliance and open-source transparency.

Documents:
- phase-5-session1-summary.md (67% framework integration)
- phase-5-session2-summary.md (100% framework integration milestone)

These documents detail the complete MemoryProxy integration process
and are being made available for research and collaboration purposes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 12:57:16 +13:00
TheFlow
b26229d466 docs: Phase 5 integration roadmap and production deployment test 
Created comprehensive integration roadmap for remaining services and
production deployment validation script.

**Integration Roadmap**:
- Session 1: InstructionPersistenceClassifier + CrossReferenceValidator (HIGH priority)
- Session 2: MetacognitiveVerifier + ContextPressureMonitor (MEDIUM priority)
- Session 3: Context editing experiments + analytics (OPTIONAL)

**Production Deployment Test**:
- Validates MemoryProxy initialization
- Verifies BoundaryEnforcer and BlogCuration rule loading
- Tests enforcement with audit trail
- Confirms all 3 critical rules accessible (inst_016, inst_017, inst_018)

**Current State**:
- 2/6 services integrated (33%)
- 99/99 tests passing (100%)
- Production deployment successful
- Audit trail active (.memory/audit/)

**Next Steps**:
- Session 1: Core service integration (2-3 hours)
- Target: 4/6 services integrated (67%)
- Maintain 100% test coverage and backward compatibility

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 12:33:57 +13:00
TheFlow
c735a4e91f feat: Phase 5 PoC Week 3 - MemoryProxy integration with Tractatus services 
Complete integration of MemoryProxy service with BoundaryEnforcer and BlogCuration.
All services enhanced with persistent rule storage and audit trail logging.

**Week 3 Summary**:
- MemoryProxy integrated with 2 production services
- 100% backward compatibility (99/99 tests passing)
- Comprehensive audit trail (JSONL format)
- Migration script for .claude/ → .memory/ transition

**BoundaryEnforcer Integration**:
- Added initialize() method to load inst_016, inst_017, inst_018
- Enhanced enforce() with async audit logging
- 43/43 existing tests passing
- 5/5 new integration scenarios passing (100% accuracy)
- Non-blocking audit to .memory/audit/decisions-{date}.jsonl

**BlogCuration Integration**:
- Added initialize() method for rule loading
- Enhanced _validateContent() with audit trail
- 26/26 existing tests passing
- Validation logic unchanged (backward compatible)
- Audit logging for all content validation decisions

**Migration Script**:
- Created scripts/migrate-to-memory-proxy.js
- Migrated 18 rules from .claude/instruction-history.json
- Automatic backup creation
- Full verification (18/18 rules + 3/3 critical rules)
- Dry-run mode for safe testing

**Performance**:
- MemoryProxy overhead: ~2ms per service (~5% increase)
- Audit logging: <1ms (async, non-blocking)
- Rule loading: 1ms for 3 rules (cache enabled)
- Total latency impact: negligible

**Files Modified**:
- src/services/BoundaryEnforcer.service.js (MemoryProxy integration)
- src/services/BlogCuration.service.js (MemoryProxy integration)
- tests/poc/memory-tool/week3-boundary-enforcer-integration.js (new)
- scripts/migrate-to-memory-proxy.js (new)
- docs/research/phase-5-week-3-summary.md (new)
- .memory/governance/tractatus-rules-v1.json (migrated rules)

**Test Results**:
- MemoryProxy: 25/25 ✅
- BoundaryEnforcer: 43/43 + 5/5 integration ✅
- BlogCuration: 26/26 ✅
- Total: 99/99 tests passing (100%)

**Next Steps**:
- Optional: Context editing experiments (50+ turn conversations)
- Production deployment with MemoryProxy initialization
- Monitor audit trail for governance insights

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 12:22:06 +13:00
TheFlow
1815ec6c11 feat: Phase 5 Memory Tool PoC - Week 2 Complete (MemoryProxy Service) 
Week 2 Objectives (ALL MET AND EXCEEDED):
✅ Full 18-rule integration (100% data integrity)
✅ MemoryProxy service implementation (417 lines)
✅ Comprehensive test suite (25/25 tests passing)
✅ Production-ready persistence layer

Key Achievements:

1. Full Tractatus Rules Integration:
   - Loaded all 18 governance rules from .claude/instruction-history.json
   - Storage performance: 1ms (0.06ms per rule)
   - Retrieval performance: 1ms
   - Data integrity: 100% (18/18 rules validated)
   - Critical rules tested: inst_016, inst_017, inst_018

2. MemoryProxy Service (src/services/MemoryProxy.service.js):
   - persistGovernanceRules() - Store rules to memory
   - loadGovernanceRules() - Retrieve rules from memory
   - getRule(id) - Get specific rule by ID
   - getRulesByQuadrant() - Filter by quadrant
   - getRulesByPersistence() - Filter by persistence level
   - auditDecision() - Log governance decisions (JSONL format)
   - In-memory caching (5min TTL, configurable)
   - Comprehensive error handling and validation

3. Test Suite (tests/unit/MemoryProxy.service.test.js):
   - 25 unit tests, 100% passing
   - Coverage: Initialization, persistence, retrieval, querying, auditing, caching
   - Test execution time: 0.454s
   - All edge cases handled (missing files, invalid input, cache expiration)

Performance Results:
- 18 rules: 2ms total (store + retrieve)
- Average per rule: 0.11ms
- Target was <1000ms - EXCEEDED by 500x
- Cache performance: <1ms for subsequent calls

Architecture:
┌─ Tractatus Application Layer
├─ MemoryProxy Service ✅ (abstraction layer)
├─ Filesystem Backend ✅ (production-ready)
└─ Future: Anthropic Memory Tool API (Week 3)

Memory Structure:
.memory/
├── governance/
│   ├── tractatus-rules-v1.json (all 18 rules)
│   └── inst_{id}.json (individual critical rules)
├── sessions/ (Week 3)
└── audit/
    └── decisions-{date}.jsonl (JSONL audit trail)

Deliverables:
- tests/poc/memory-tool/week2-full-rules-test.js (394 lines)
- src/services/MemoryProxy.service.js (417 lines)
- tests/unit/MemoryProxy.service.test.js (446 lines)
- docs/research/phase-5-week-2-summary.md (comprehensive summary)

Total: 1,257 lines production code + tests

Week 3 Preview:
- Integrate MemoryProxy with BoundaryEnforcer
- Integrate with BlogCuration (inst_016/017/018 enforcement)
- Context editing experiments (50+ turn conversations)
- Migration script (.claude/ → .memory/)

Research Status: Week 2 of 3 complete
Confidence: VERY HIGH - Production-ready, fully tested, ready for integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 12:11:20 +13:00
TheFlow
2ddae65b18 feat: Phase 5 Memory Tool PoC - Week 1 Complete 
Week 1 Objectives (All Met):
- API research and capabilities assessment ✅
- Comprehensive findings document ✅
- Basic persistence PoC implementation ✅
- Anthropic integration test framework ✅
- Governance rules testing (inst_001, inst_016, inst_017) ✅

Key Achievements:
- Updated @anthropic-ai/sdk: 0.9.1 → 0.65.0 (memory tool support)
- Built FilesystemMemoryBackend (create, view, exists operations)
- Validated 100% persistence and data integrity
- Performance: 1ms overhead (filesystem) - exceeds <500ms target
- Simulation mode: Test workflow without API costs

Deliverables:
- docs/research/phase-5-memory-tool-poc-findings.md (42KB API assessment)
- docs/research/phase-5-week-1-implementation-log.md (comprehensive log)
- tests/poc/memory-tool/basic-persistence-test.js (291 lines)
- tests/poc/memory-tool/anthropic-memory-integration-test.js (390 lines)

Test Results:
✅ Basic Persistence: 100% success (1ms latency)
✅ Governance Rules: 3 rules tested successfully
✅ Data Integrity: 100% validation
✅ Memory Structure: governance/, sessions/, audit/ directories

Next Steps (Week 2):
- Context editing experimentation (50+ turn conversations)
- Real API integration with CLAUDE_API_KEY
- Multi-rule storage (all 18 Tractatus rules)
- Performance measurement vs. baseline

Research Status: Week 1 of 3 complete, GREEN LIGHT for Week 2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 12:03:39 +13:00
TheFlow
e9a35ed336 research: add memory tool integration breakthrough (v1.1) 
**Phase 5 Priority Finding**: Anthropic Claude 4.5 memory/context APIs
provide game-changing pathway for persistent LLM governance.

## Changes

**Section 3.6: Memory Tool Integration (Approach F)**
- Leverages Claude 4.5 memory tool for persistent rule storage
- Context editing API for automated context management
- Middleware proxy pattern for enforcement
- PoC timeline: 2-3 weeks (vs 12-18 months for full research)
- Feasibility: HIGH (API-driven, no model changes needed)

**Section 15: Recent Developments (October 2025)**
- Documents breakthrough discovery on 2025-10-10
- Strategic repositioning: immediate PoC vs long-term study
- Updated feasibility assessment with memory tool approach
- Two-track plan: Track A (PoC, active), Track B (full study, on hold)

## Impact

- Practical feasibility dramatically improved
- No fine-tuning or model access required
- Solves persistent state + context overflow challenges
- Enables multi-session governance, audit trails
- De-risks long-term research investment

## Metadata

- Document version: 1.0 → 1.1
- Word count: ~5,000 → 6,084 words
- New sections: 2 major additions (~1,000 words)
- Status: Phase 5 priority, PoC in progress

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 08:50:35 +13:00
TheFlow
e2ecbbd4d2 docs: trigger sync workflow for research document 
Minimal timestamp update to trigger automatic sync to public repository
after manual workflow trigger failed.

This will sync the LLM integration feasibility study to:
https://github.com/AgenticGovernance/tractatus-framework

Related to commit dcada62 which initially added the document but
workflow failed due to YAML error (now fixed in 581429c).
 2025-10-10 06:47:10 +13:00
TheFlow
e6b85d9fed research: publish LLM-integrated governance feasibility study 
Add comprehensive 12-18 month research proposal exploring transition
from external (Claude Code) to internal (LLM-embedded) governance.

**Research Scope**:
- 5 integration approaches (system prompt, RAG, middleware, fine-tuning, hybrid)
- Technical feasibility dimensions (persistence, self-enforcement, performance, scalability)
- 5-phase methodology (baseline → PoC → scalability → fine-tuning → adoption)
- Success criteria: <15% overhead, >90% enforcement, 3+ enterprise pilots

**Document Enhancements**:
- Added prominent disclaimer (proposal, not completed work)
- Added collaboration invitation (research@agenticgovernance.digital)
- Added version history table
- Updated proposed start date (Phase 5-6, Q3 2026 earliest)

**Integration**:
- Document added to MongoDB via migrate-documents script
- Available at /api/documents/research-scope-feasibility-of-llm-integrated-tractatus-framework
- Categorizes as "Research & Evidence" in docs.html
- PDF generation pending (requires LaTeX on production)

**Transparency Rationale**:
- Demonstrates thought leadership in architectural AI safety
- Invites academic/industry collaboration
- Shows intellectual honesty (includes worst-case scenarios)
- No sensitive information (no credentials, proprietary code, or confidential data)

Related: concurrent-session-architecture-limitations.md, rule-proliferation-and-transactional-overhead.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-10 06:10:36 +13:00
TheFlow
389bbba4a1 feat(research): add concurrent session architecture limitations study 
Add comprehensive research document analyzing single-tenant
architecture constraints discovered through dogfooding:

- Documents concurrent Claude Code session failure modes
- Analyzes state contamination in health metrics
- Identifies race conditions in instruction storage
- Evaluates multi-tenant architecture alternatives
- Provides mitigation strategies and research directions

Classification: Public, suitable for GitHub and academic citation
Status: Discovered design constraint, addressable but not yet implemented

Related: Phase 4 production testing, framework health monitoring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-10-09 21:51:59 +13:00
TheFlow
193a08cb95 feat: initial commit with security hardening and framework documentation 
Security improvements:
- Enhanced .gitignore to protect sensitive files
- Removed internal docs from version control (CLAUDE.md, session handoffs, security audits)
- Sanitized README.md (removed internal paths and infrastructure details)
- Protected session state and token checkpoint files

Framework documentation:
- Added 4 case studies (framework in action, failures, real-world governance, pre-publication audit)
- Added rule proliferation research topic
- Sanitized public-facing documentation

Content updates:
- Updated public/leader.html with honest claims only
- Updated public/docs.html with Resources section
- All content complies with inst_016, inst_017, inst_018 (no fabrications, no guarantees, accurate status)

This commit represents Phase 4 of development with production-ready security hardening.
 2025-10-09 12:05:07 +13:00