From 1c22371da2c92a0dc8151b48d618a7cab8b8c502 Mon Sep 17 00:00:00 2001 From: TheFlow Date: Thu, 30 Oct 2025 22:20:58 +1300 Subject: [PATCH] feat(framework): integrate Alexander principles and Q&A tracking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add inst_090-094: Christopher Alexander architectural principles - Deep Interlock (service coordination) - Structure-Preserving (audit continuity) - Gradients Not Binary (intensity levels) - Living Process (evolves from failures) - Not-Separateness (architectural integration) - Add inst_095: Q&A tracking protocol (bidirectional) - Framework version: 4.2 β†’ 4.4 - Active instructions: 62 β†’ 68 - Integration scripts for safe deployment πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- scripts/add-inst-095.js | 97 +++++++++++++++ scripts/integrate-alexander-rules.js | 174 +++++++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100755 scripts/add-inst-095.js create mode 100755 scripts/integrate-alexander-rules.js diff --git a/scripts/add-inst-095.js b/scripts/add-inst-095.js new file mode 100755 index 00000000..cb08e515 --- /dev/null +++ b/scripts/add-inst-095.js @@ -0,0 +1,97 @@ +#!/usr/bin/env node + +/** + * Add inst_095: Question Tracking and Clarification Protocol + * + * Addresses communication gap: missed questions in both directions + */ + +const fs = require('fs'); +const path = require('path'); + +const INSTRUCTION_HISTORY_PATH = path.join(__dirname, '../.claude/instruction-history.json'); + +const inst095 = { + id: "inst_095", + text: "Track all questions in both directions (Userβ†’Claude and Claudeβ†’User). At end of each interaction, verify all questions have been addressed. Issue explicit alert if question remains unanswered. Apply to terminal interactions and documentation.", + timestamp: new Date().toISOString(), + quadrant: "OPERATIONAL", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "REQUIRED", + explicitness: 0.92, + source: "user_instruction", + session_id: "2025-10-30-qa-tracking", + parameters: { + tracking_scope: ["terminal", "documentation", "plan_mode"], + alert_threshold: "immediate", + question_types: ["explicit_query", "clarification_request", "decision_point"], + exempt_patterns: ["rhetorical_question"] + }, + active: true, + notes: "Question Tracking and Clarification Protocol - Prevents missed questions in busy prompts and cross-session interactions" +}; + +function main() { + console.log('═══════════════════════════════════════════════════════════'); + console.log(' Adding inst_095: Question Tracking Protocol'); + console.log('═══════════════════════════════════════════════════════════\n'); + + // Read current instruction history + let history; + try { + history = JSON.parse(fs.readFileSync(INSTRUCTION_HISTORY_PATH, 'utf8')); + } catch (err) { + console.error('❌ Error reading instruction-history.json:', err.message); + process.exit(1); + } + + console.log(`πŸ“– Current version: ${history.version}`); + console.log(` Total instructions: ${history.instructions.length}`); + console.log(` Active instructions: ${history.instructions.filter(i => i.active).length}\n`); + + // Check if inst_095 already exists + const existing = history.instructions.find(i => i.id === 'inst_095'); + + if (existing) { + console.log('⚠️ inst_095 already exists:'); + console.log(` ${existing.text.substring(0, 60)}...`); + console.log('\n❌ Aborting to prevent duplicate\n'); + process.exit(1); + } + + // Add inst_095 + console.log('✨ Adding inst_095:\n'); + history.instructions.push(inst095); + console.log(` βœ“ ${inst095.id}: ${inst095.text.substring(0, 80)}...`); + + // Update version if appropriate (4.3 β†’ 4.4 with Q&A tracking) + const shouldUpdateVersion = history.version === "4.3"; + if (shouldUpdateVersion) { + history.version = "4.4"; + console.log(`\nπŸ“¦ Updated version: ${history.version}`); + } + + history.last_updated = new Date().toISOString(); + + console.log(` Total instructions: ${history.instructions.length}`); + console.log(` Active instructions: ${history.instructions.filter(i => i.active).length}\n`); + + // Write back to file + try { + fs.writeFileSync(INSTRUCTION_HISTORY_PATH, JSON.stringify(history, null, 2), 'utf8'); + } catch (err) { + console.error('❌ Error writing instruction-history.json:', err.message); + process.exit(1); + } + + console.log('βœ… Integration complete!\n'); + console.log('═══════════════════════════════════════════════════════════'); + console.log(' Next Steps:'); + console.log('═══════════════════════════════════════════════════════════\n'); + console.log('1. Run: node scripts/sync-instructions-to-db.js'); + console.log('2. Test with next interaction (Q&A tracking active)'); + console.log('3. Monitor effectiveness over coming sessions\n'); +} + +main(); diff --git a/scripts/integrate-alexander-rules.js b/scripts/integrate-alexander-rules.js new file mode 100755 index 00000000..1c585a27 --- /dev/null +++ b/scripts/integrate-alexander-rules.js @@ -0,0 +1,174 @@ +#!/usr/bin/env node + +/** + * Integrate Christopher Alexander Pattern Rules (inst_090-094) + * + * Adds the 5 Alexander pattern rules to instruction-history.json + * and updates framework version from 4.2 to 4.3 + * + * Source: docs/governance/ALEXANDER-PATTERN-RULES.md + */ + +const fs = require('fs'); +const path = require('path'); + +const INSTRUCTION_HISTORY_PATH = path.join(__dirname, '../.claude/instruction-history.json'); + +// The 5 Alexander Pattern Rules +const alexanderRules = [ + { + id: "inst_090", + text: "Six governance services must reinforce each other through mutual validation, creating deep interlock rather than isolated enforcement", + timestamp: new Date().toISOString(), + quadrant: "STRATEGIC", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "REQUIRED", + explicitness: 0.90, + source: "architectural_principle", + session_id: "2025-10-30-alexander-integration", + parameters: { + services: ["BoundaryEnforcer", "CrossReferenceValidator", "MetacognitiveVerifier", "ContextPressureMonitor", "InstructionPersistenceClassifier", "PluralisticDeliberationOrchestrator"], + principle: "deep_interlock" + }, + active: true, + notes: "Centers Reinforce Centers - Deep Interlock principle from Christopher Alexander" + }, + { + id: "inst_091", + text: "Framework changes must preserve wholeness - existing audit logs remain interpretable, prior governance decisions remain valid, instruction precedents maintain authority", + timestamp: new Date().toISOString(), + quadrant: "STRATEGIC", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "MANDATORY", + explicitness: 0.95, + source: "architectural_principle", + session_id: "2025-10-30-alexander-integration", + parameters: { + principle: "structure_preserving_transformation", + preservation_targets: ["audit_logs", "governance_decisions", "instruction_precedents"] + }, + active: true, + notes: "Structure-Preserving Transformations Only - Enhance wholeness while maintaining coherence" + }, + { + id: "inst_092", + text: "Governance operates on gradients (NORMAL/ELEVATED/HIGH/CRITICAL context pressure, LOW/MEDIUM/HIGH persistence) rather than binary yes/no switches", + timestamp: new Date().toISOString(), + quadrant: "STRATEGIC", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "REQUIRED", + explicitness: 0.88, + source: "architectural_principle", + session_id: "2025-10-30-alexander-integration", + parameters: { + principle: "gradients_not_binary", + examples: ["context_pressure_levels", "persistence_levels", "verification_requirements"] + }, + active: true, + notes: "Gradients Over Binary Switches - Natural systems use gradients, not binary switches" + }, + { + id: "inst_093", + text: "Framework evolves through real-world use and feedback, not top-down specification - governance grows from failures and successes, not predetermined plans", + timestamp: new Date().toISOString(), + quadrant: "STRATEGIC", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "REQUIRED", + explicitness: 0.85, + source: "architectural_principle", + session_id: "2025-10-30-alexander-integration", + parameters: { + principle: "living_process", + evolution_triggers: ["real_failures", "audit_log_analysis", "governance_gaps", "user_feedback"] + }, + active: true, + notes: "Living Process Over Fixed Design - Systems grow organically through use" + }, + { + id: "inst_094", + text: "Governance must be woven into AI deployment architecture, not bolted on as separate compliance layer - if AI can execute without governance validation, framework is separate (and will be bypassed)", + timestamp: new Date().toISOString(), + quadrant: "STRATEGIC", + persistence: "HIGH", + temporal_scope: "PERMANENT", + verification_required: "MANDATORY", + explicitness: 0.93, + source: "architectural_principle", + session_id: "2025-10-30-alexander-integration", + parameters: { + principle: "not_separateness", + integration_test: "can_ai_bypass_governance" + }, + active: true, + notes: "Not-Separateness (Framework Integration) - Deep integration, not bolt-on compliance" + } +]; + +function main() { + console.log('═══════════════════════════════════════════════════════════'); + console.log(' Integrating Christopher Alexander Pattern Rules'); + console.log('═══════════════════════════════════════════════════════════\n'); + + // Read current instruction history + let history; + try { + history = JSON.parse(fs.readFileSync(INSTRUCTION_HISTORY_PATH, 'utf8')); + } catch (err) { + console.error('❌ Error reading instruction-history.json:', err.message); + process.exit(1); + } + + console.log(`πŸ“– Current version: ${history.version}`); + console.log(` Total instructions: ${history.instructions.length}`); + console.log(` Active instructions: ${history.instructions.filter(i => i.active).length}\n`); + + // Check if Alexander rules already exist + const existingAlexander = history.instructions.filter(i => + i.id >= 'inst_090' && i.id <= 'inst_094' + ); + + if (existingAlexander.length > 0) { + console.log('⚠️ Alexander rules already exist:'); + existingAlexander.forEach(i => console.log(` ${i.id}: ${i.text.substring(0, 60)}...`)); + console.log('\n❌ Aborting integration to prevent duplicates'); + console.log(' Delete existing rules first or use a different approach\n'); + process.exit(1); + } + + // Add Alexander rules + console.log('✨ Adding 5 Alexander Pattern Rules:\n'); + alexanderRules.forEach(rule => { + history.instructions.push(rule); + console.log(` βœ“ ${rule.id}: ${rule.text.substring(0, 60)}...`); + }); + + // Update version + history.version = "4.3"; + history.last_updated = new Date().toISOString(); + + console.log(`\nπŸ“¦ Updated version: ${history.version}`); + console.log(` Total instructions: ${history.instructions.length}`); + console.log(` Active instructions: ${history.instructions.filter(i => i.active).length}\n`); + + // Write back to file + try { + fs.writeFileSync(INSTRUCTION_HISTORY_PATH, JSON.stringify(history, null, 2), 'utf8'); + } catch (err) { + console.error('❌ Error writing instruction-history.json:', err.message); + process.exit(1); + } + + console.log('βœ… Integration complete!\n'); + console.log('═══════════════════════════════════════════════════════════'); + console.log(' Next Steps:'); + console.log('═══════════════════════════════════════════════════════════\n'); + console.log('1. Run: node scripts/sync-instructions-to-db.js'); + console.log('2. Verify framework with: node scripts/framework-stats.js'); + console.log('3. Test integration with: node scripts/session-init.js\n'); +} + +main();