From 974f812509f8d5a3c8a061d8509a7285f86ba08a Mon Sep 17 00:00:00 2001 From: TheFlow Date: Sun, 12 Oct 2025 16:37:09 +1300 Subject: [PATCH] docs: update maintenance guide and README for 6th core service MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document PluralisticDeliberationOrchestrator as 6th mandatory service - Update service initialization procedures - Add value pluralism governance principles - Update README with current framework status Reflects production-ready 6-service architecture πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE_Tractatus_Maintenance_Guide.md | 204 +++++++++++++++++++++++++- README.md | 105 +------------ 2 files changed, 207 insertions(+), 102 deletions(-) diff --git a/CLAUDE_Tractatus_Maintenance_Guide.md b/CLAUDE_Tractatus_Maintenance_Guide.md index 6693072c..56b4a41a 100644 --- a/CLAUDE_Tractatus_Maintenance_Guide.md +++ b/CLAUDE_Tractatus_Maintenance_Guide.md @@ -91,9 +91,9 @@ tractatus_dev.koha_donations // Phase 3 ## Tractatus Framework Governance -### Core Services - Five Mandatory Components +### Core Services - Six Mandatory Components -**All five MUST be active throughout every session. Framework fade = critical failure.** +**All six MUST be active throughout every session. Framework fade = critical failure.** ### What is a "27027 Failure"? @@ -260,6 +260,206 @@ node scripts/check-session-pressure.js --tokens / --messages safety or safety > privacy) +- **Provisional Agreement**: Decisions are reviewable, not permanent rules + +**Files updated**: +- `.claude/session-state.json` (last_framework_activity.PluralisticDeliberationOrchestrator) +- Precedent database (new deliberation outcomes) +- Stakeholder communications log + +**Human Oversight**: MANDATORY +- AI facilitates, humans decide (TRA-OPS-0002) +- Stakeholder list requires human approval +- Deliberation outcomes require human approval +- Values decisions NEVER automated + +--- + +### Key Framework Instructions + +**Critical instructions from `.claude/instruction-history.json` for quick reference** + +These instructions modify Claude's behavior to align with Tractatus principles. Full instruction database in `.claude/instruction-history.json`. + +#### inst_028: Adaptive Communication Tone +**Purpose**: Prevent linguistic hierarchy in stakeholder deliberation +**Persistence**: HIGH | **Quadrant**: OPS | **Scope**: SESSION + +**Instruction**: +Detect and mirror stakeholder communication style: +- Formal academic β†’ respond formally with citations +- Casual/direct β†’ respond conversationally, no jargon +- Technical β†’ use precise terminology +- Plain language β†’ avoid specialist terms +- Never impose corporate/academic tone by default +- Test: If you'd sound weird at a pub, you're too formal + +**Application**: +When communicating with Australian/NZ stakeholders, use direct language. When communicating with academic researchers, use formal register. Same message, different styles - prevents exclusion through linguistic norms. + +**Related**: PluralisticDeliberationOrchestrator, AdaptiveCommunicationOrchestrator + +--- + +#### inst_029: Anti-Patronizing Language Filter +**Purpose**: Prevent condescension that reproduces power imbalances +**Persistence**: HIGH | **Quadrant**: STR | **Scope**: PERMANENT + +**Instruction**: +Flag patronizing patterns before sending: +- "Simply...", "Just...", "Obviously..." +- "As you may know...", "It's easy to..." +- Explaining basics to experts +- Oversimplification when detail requested +- Block message until revised. Assume intelligence. + +**Application**: +Before sending any communication to stakeholders, scan for patronizing language. If detected, BLOCK and revise. This is not politeness - it's preventing elite capture where dominant groups dismiss alternative perspectives as "confused." + +**Related**: Deliberative democracy (Iris Marion Young's critique of formal equality) + +--- + +#### inst_030: Regional Communication Norms +**Purpose**: Respect diverse cultural communication styles +**Persistence**: MEDIUM | **Quadrant**: TAC | **Scope**: SESSION + +**Instruction**: +Adapt to regional communication norms: + +**Australian/NZ context**: +- Value directness over diplomatic cushioning +- "Mate" appropriate in casual contexts +- Brevity respected +- Anti-tall-poppy (avoid excessive formality) +- Understatement valued ("not bad" = excellent) + +**Japanese context**: +- Indirectness to preserve harmony (honne/tatemae) +- Formal register shows respect +- Silence is meaningful, not awkward +- Group consensus before stating position + +**Te Reo Māori protocols**: +- Begin with mihi (greeting), acknowledge whakapapa +- Use communal framing (whānau, iwi, not just individual) +- Respect tapu/noa distinctions +- Seek consensus (kotahitanga) + +**Detection**: .au/.nz/.jp domains, language, self-identification, slang + +**Application**: +When facilitating pluralistic deliberation with diverse stakeholders, adapt communication structure (not just language translation). Australian stakeholder receives direct summary, Japanese stakeholder receives formal acknowledgment with indirect exploration of concerns, Māori stakeholder receives communal framing with mihi. + +**Related**: Cross-cultural deliberation, high/low context communication theory + +--- + +#### inst_031: Multilingual Engagement Protocol +**Purpose**: Enable deliberation across language barriers +**Persistence**: HIGH | **Quadrant**: OPS | **Scope**: PERMANENT + +**Instruction**: +When non-English input detected: +1. Respond in sender's language if capable +2. If not: "Kia ora! I detected [language] but will respond in English. Translation resources: [link]" +3. Never assume English proficiency +4. Offer translation of key documents +5. Acknowledge language barriers respectfully +6. For multilingual deliberations: + - Provide simultaneous translation + - Allow extra time for comprehension + - Check understanding in both directions + +**Application**: +If stakeholder submits input in Māori, respond in Māori if capable. If not, acknowledge the language respectfully and explain English response. For deliberations with multilingual participants, provide translation and verify understanding across languages - don't privilege English speakers. + +**Related**: Linguistic justice, inclusive deliberation + --- ## Session Management diff --git a/README.md b/README.md index 8966e249..922ca31f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The world's first production implementation of architectural AI safety guarantee [![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-192%20passing-brightgreen.svg)](https://github.com/AgenticGovernance/tractatus-framework) +[![Tests](https://img.shields.io/badge/Tests-637%20passing-brightgreen.svg)](https://github.com/AgenticGovernance/tractatus-framework) --- @@ -150,101 +150,6 @@ const verification = verifier.verify({ --- -## πŸ”§ Rule Manager - -The **Rule Manager** is a web-based administration interface for managing governance rules in the Tractatus framework. It replaces the fragile `.claude/instruction-history.json` file with a robust, database-backed solution supporting multi-project governance. - -### Key Features - -- **🌐 Multi-Project Governance** - Apply rules universally across projects or scope them to specific projects -- **βœ… Real-Time Validation** - Ensure rules meet framework quality standards -- **πŸ”„ Variable Substitution** - Use `${VAR_NAME}` placeholders for project-specific values -- **πŸ“Š Quality Scoring** - AI-calculated clarity, specificity, and actionability metrics -- **πŸ” Advanced Filtering** - Search by scope, quadrant, persistence, validation status -- **πŸ“ˆ Dashboard Analytics** - Track rule usage, enforcement counts, and quality trends - -### Quick Start - -1. **Access the Rule Manager**: - ``` - http://localhost:9000/admin/rule-manager.html - ``` - -2. **Create a new rule**: - ```javascript - { - rule_id: "inst_019", - text: "Database MUST use ${DB_TYPE} on port ${DB_PORT}", - quadrant: "SYSTEM", - persistence: "HIGH", - scope: "UNIVERSAL" // Applies to all projects - } - ``` - -3. **Apply across projects**: - - Universal rules are automatically inherited - - Variables are substituted per-project (e.g., `${DB_TYPE}` β†’ `MongoDB`) - - Project-specific rules override when needed - -### Rule Properties - -Each rule includes: - -| Property | Description | Example | -|----------|-------------|---------| -| **Rule ID** | Unique identifier | `inst_019` | -| **Text** | Governance instruction | `"Port MUST be ${PORT}"` | -| **Quadrant** | Framework category | `SYSTEM` | -| **Persistence** | Enforcement duration | `HIGH`, `MEDIUM`, `LOW` | -| **Scope** | Application range | `UNIVERSAL`, `PROJECT_SPECIFIC` | -| **Priority** | Conflict resolution order | `0-100` | -| **Clarity Score** | Quality metric | `85%` (Green) | - -### Documentation - -- **πŸ“˜ User Guide**: [docs/USER_GUIDE_RULE_MANAGER.md](docs/USER_GUIDE_RULE_MANAGER.md) - Complete walkthrough of the interface -- **πŸ”Œ API Reference**: [docs/api/RULES_API.md](docs/api/RULES_API.md) - REST API documentation for developers -- **πŸ“‹ Implementation Plan**: [docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md](docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md) - Technical architecture - -### Example: Managing the 27027 Rule - -**Before (fragile JSON file)**: -```json -{ - "inst_005": { - "text": "MongoDB port is 27027", - "persistence": "HIGH" - } -} -``` - -**After (Rule Manager)**: -```javascript -// Create universal rule with variables -{ - rule_id: "inst_005", - text: "MongoDB MUST use port ${MONGODB_PORT} for ${PROJECT_NAME} database", - scope: "UNIVERSAL", - variables: ["MONGODB_PORT", "PROJECT_NAME"], - clarity_score: 92 // Automatically calculated -} - -// Apply to tractatus project -variables: { MONGODB_PORT: "27027", PROJECT_NAME: "tractatus" } - -// Apply to other project -variables: { MONGODB_PORT: "27017", PROJECT_NAME: "family-history" } -``` - -**Benefits**: -- βœ… No more manual JSON editing -- βœ… Real-time validation prevents syntax errors -- βœ… Variable detection is automatic -- βœ… Clarity scores guide improvement -- βœ… Reusable across projects - ---- - ## πŸ’‘ Real-World Examples ### The 27027 Incident @@ -325,7 +230,7 @@ npm run test:security npm run test:watch ``` -**Test Coverage**: 192 tests, 100% coverage of core services +**Test Coverage**: 637 tests across 22 test files, 100% coverage of core services --- @@ -359,8 +264,8 @@ tractatus/ As the framework learns from failures, instruction count grows: - **Phase 1:** 6 instructions -- **Current:** 18 instructions (+200%) -- **Projected (12 months):** 40-50 instructions +- **Current:** 28 instructions (+367%) +- **Projected (12 months):** 50-60 instructions **The concern:** At what point does rule proliferation reduce framework effectiveness? @@ -405,7 +310,7 @@ We welcome contributions in several areas: **Phase 1**: βœ… Complete (October 2025) - All 5 core services implemented -- 192 unit tests (100% coverage) +- 637 tests across 22 test files (100% coverage of core services) - Production deployment active - This website built using Tractatus governance