tractatus/docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN_v2.md

Multi-Project Governance System - Implementation Plan v2.0

Project: Tractatus Agentic Governance Framework Scope: AI-Powered Rule Management + Multi-Project Infrastructure Standard: World-class design and implementation Target: Potential commercial product for Claude Code users Status: ✅ Validated via Family-History Integration (Nov 2025)

---

🎯 Executive Summary

Transform Tractatus from a single-project governance framework into a multi-project, AI-powered governance platform that:

1. Replaces fragile CLAUDE.md with validated, optimized governance rules
2. Enables multi-project management across portfolio with variable substitution
3. Provides AI-assisted rule optimization for clarity and effectiveness
4. Offers project templates for instant deployment to new projects
5. Validates rules in real-time using the 6 core Tractatus services
6. Enforces governance automatically via PreToolUse hooks
7. Modernizes deployment with unified, secure scripts

Commercial Potential: Solo developers to enterprise teams managing multiple AI-assisted projects

✅ Real-World Validation

November 2025: Successfully integrated Tractatus Framework into Family-History project, a multi-tenant SaaS platform. This integration validated the approach and uncovered critical insights:

• ✅ Hook system works brilliantly (automatic governance enforcement)
• ✅ Multi-tenant architecture requires GovernanceAuditLog (tenant-aware, not filtered)
• ✅ AsyncLocalStorage provides elegant tenant context
• ✅ Deployment modernization delivers massive value (134 scripts → 1)
• ✅ Framework services adapt cleanly across projects
• ✅ Time estimates validated (most phases accurate within 20%)

Key Insight: The hook system is the killer feature, not an afterthought. It should be Phase 0.

---

📚 Lessons from Real-World Integration

Family-History Integration (Nov 1-2, 2025)

Project Context:

• Multi-tenant SaaS (family genealogy platform)
• Node.js + Express + MongoDB (port 27027)
• Production: OVHCloud VPS
• 31 governance rules, 6 framework services
• 134 ad-hoc deployment scripts

Integration Timeline:

• Phase 1: Framework installation & adaptation (3 hours)
• Phase 2: Multi-tenant enhancements (2 hours)
• Phase 3: Hook system import (1 hour)
• Phase 4: Deployment modernization (2 hours)
• Total: ~8 hours for full integration

What Worked Brilliantly ✅

1. Hook System (framework-audit-hook.js)

• Impact: Automatic governance enforcement on Edit/Write operations
• Integration: 1 hour to adapt, configure in .claude/settings.local.json
• Value: Eliminates manual governance, provides real-time feedback
• Learning: This should be Phase 0, not buried in implementation

Code Example:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/framework-audit-hook.js",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

2. GovernanceAuditLog Architecture

• Discovery: Need separate audit logs for governance vs user actions
• Implementation: Platform-wide, tenant-aware (not tenant-filtered)
• Pattern:

  // User actions (tenant-filtered)
  AuditLog → audit_logs collection (per-tenant)
  
  // Governance decisions (platform-wide, tenant-aware)
  GovernanceAuditLog → governance_audit_logs collection (all tenants)
  

• Learning: Multi-tenant projects need both logs with different isolation models

3. AsyncLocalStorage Tenant Context

• Challenge: Framework services needed tenant awareness without tight coupling
• Solution: getCurrentTenant() from AsyncLocalStorage
• Implementation: Updated all 6 services in ~2 hours
• Learning: Clean, elegant pattern for multi-tenant governance

Code Example:

// In framework service
const { getCurrentTenant } = require('../utils/tenantContext');

_auditDecision(result, action, context) {
  const tenantId = getCurrentTenant();  // null if no tenant context

  GovernanceAuditLog.logDecision({
    tenantId,  // Recorded for context, not for filtering
    service: 'BoundaryEnforcer',
    decision: { allowed: result.allowed, ... },
    // ... rest of audit data
  });
}

4. Deployment Modernization

• Problem: 134 ad-hoc deployment scripts, inconsistent, no security checks
• Solution: One unified deploy.sh with security checks, cache busting, dry-run
• Impact: Massive improvement in deployment reliability and developer experience
• Learning: This is a major value-add, should be highlighted in plan

Features Implemented:

# Security checks
- Multi-tenant safety (no hardcoded tenant IDs)
- localStorage violations (blocks deployment)
- Local testing verification
- Uncommitted changes warning

# Capabilities
- Dry-run preview
- Automatic cache busting (DEPLOYMENT_VERSION)
- Smart restart detection
- Health checks
- Compiled HTML cleanup

5. Framework Adaptation Pattern

• MemoryProxy: Made optional (not needed in family-history)
• MongoDB Port: Easy to change (27017 → 27027)
• Models: Optional (SessionState, VerificationLog)
• Learning: Framework is adaptable, not rigid

Adaptation Checklist:

// 1. Update MongoDB connection
mongoose.connect('mongodb://localhost:27027/family_history')

// 2. Make MemoryProxy optional
this.memoryProxy = null;  // Instead of getMemoryProxy()

// 3. Add tenant context
const { getCurrentTenant } = require('../utils/tenantContext');

// 4. Use GovernanceAuditLog
const GovernanceAuditLog = require('../models/GovernanceAuditLog');

What Needs Improvement 🔄

1. Phase Sequencing

• Issue: Hook system not mentioned until deep in plan
• Fix: Make it Phase 0 (prerequisite)
• Reason: Hooks provide immediate value, demonstrate framework power

2. Multi-Tenant Clarity

• Issue: Plan doesn't distinguish tenant-filtered vs tenant-aware
• Fix: Clear architectural diagrams showing both patterns
• Reason: Critical distinction for multi-tenant projects

3. Deployment Emphasis

• Issue: Deployment not in original plan at all
• Fix: Add as separate phase with high priority
• Reason: Replacing 134 scripts is a major win, sells the value

4. Time Estimates

• Issue: Some estimates were accurate, others optimistic
• Fix: Update based on family-history actual times
• Accuracy: Most phases within 20%, some tasks faster than expected

Validated Time Estimates

Task	Planned	Actual	Delta
Framework installation	2-3 hours	3 hours	On target
Multi-tenant adaptation	3-4 hours	2 hours	Faster
Hook system import	Not planned	1 hour	New
Deployment modernization	Not planned	2 hours	New
GovernanceAuditLog model	Not planned	1 hour	New
Total Integration	N/A	8 hours	Baseline

Integration Success Metrics

Framework Services:

• ✅ All 6 services ACTIVE
• ✅ 31 governance rules loaded
• ✅ Zero runtime errors
• ✅ Hook system configured
• ✅ GovernanceAuditLog operational

Deployment:

• ✅ Unified script created
• ✅ Security checks implemented
• ✅ Dry-run tested successfully
• ✅ Cache busting working
• ✅ Backward compatible

Documentation:

• ✅ Comprehensive session handoff created
• ✅ All files documented with line numbers
• ✅ Architecture diagrams updated
• ✅ Next steps clearly defined

---

📐 Updated System Architecture

Three-Tier Governance System

┌─────────────────────────────────────────────────────────────┐
│ TIER 0: HOOK ENFORCEMENT LAYER (NEW)                        │
│ • PreToolUse hooks intercept Edit/Write/Bash                │
│ • Automatic governance enforcement                          │
│ • Real-time feedback via systemMessage                      │
│ • Logs to GovernanceAuditLog                                │
└─────────────────────────────────────────────────────────────┘
                         ↓ enforces
┌─────────────────────────────────────────────────────────────┐
│ TIER 1: UNIVERSAL RULES                                     │
│ • Apply to ALL projects                                     │
│ • Contain variables: ${DB_PORT}, ${PROJECT_NAME}            │
│ • Example: "Database MUST use ${DB_TYPE}"                   │
└─────────────────────────────────────────────────────────────┘
                         ↓ inherited by
┌─────────────────────────────────────────────────────────────┐
│ TIER 2: PROJECT-INHERITED RULES                             │
│ • Universal rules with project variables applied            │
│ • Tractatus: ${DB_TYPE} → MongoDB                           │
│ • Family-History: ${DB_TYPE} → MongoDB, ${DB_PORT} → 27027  │
└─────────────────────────────────────────────────────────────┘
                         + combined with
┌─────────────────────────────────────────────────────────────┐
│ TIER 3: PROJECT-SPECIFIC RULES                              │
│ • Unique to one project                                     │
│ • Example: "TenantStorage MUST be used (no localStorage)"  │
│ • Family-History: Multi-tenant security rules               │
└─────────────────────────────────────────────────────────────┘

Multi-Tenant Audit Architecture (Validated Pattern)

┌──────────────────────────────────────────────────────────────┐
│ USER ACTIONS (Tenant-Filtered)                               │
│                                                               │
│  User Action → AuditLog Model → audit_logs collection       │
│                                                               │
│  • tenantFilter plugin applied                               │
│  • Each tenant sees only their data                          │
│  • Example: User uploads photo, user edits profile          │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ GOVERNANCE DECISIONS (Platform-Wide, Tenant-Aware)           │
│                                                               │
│  Framework → GovernanceAuditLog → governance_audit_logs      │
│                                                               │
│  • NO tenant filtering (platform-wide)                       │
│  • Records tenantId for context                              │
│  • Visible to platform admins                                │
│  • Example: BoundaryEnforcer blocks Edit, pressure warning  │
└──────────────────────────────────────────────────────────────┘

Why This Matters:

• User AuditLog: Legal compliance, per-tenant data isolation
• GovernanceAuditLog: Framework analytics, cross-tenant patterns, security monitoring

Tenant Context Flow (Validated)

┌─────────────────────────────────────────────────────────────┐
│ Request Lifecycle                                            │
│                                                               │
│  1. HTTP Request                                             │
│  2. tenantContextMiddleware                                  │
│      ↓ sets                                                  │
│  3. AsyncLocalStorage.run(tenant, ...)                       │
│      ↓ available to                                          │
│  4. Framework Services                                       │
│      ↓ call                                                  │
│  5. getCurrentTenant()                                       │
│      ↓ returns                                               │
│  6. tenantId (or null)                                       │
│      ↓ logged in                                             │
│  7. GovernanceAuditLog                                       │
└─────────────────────────────────────────────────────────────┘

Core Components (Updated)

Frontend (Vanilla JS + Tailwind)
├── Rule Manager Dashboard
├── Rule Editor with AI Assistant
├── Project Manager Dashboard
├── CLAUDE.md Migration Wizard
├── Project Configuration Editor
└── Deployment Manager (NEW)

Backend (Node.js + Express)
├── Rule Management API
├── Project Management API
├── Deployment API (NEW)
├── AI Services
│   ├── RuleOptimizer.service.js
│   ├── ClaudeMdAnalyzer.service.js
│   ├── RuleSuggestionEngine.service.js
│   └── RuleInterpolator.service.js
├── Validation Engine
│   └── RuleValidator.service.js (integrates 6 core services)
├── Template System
└── Hook System (NEW - Phase 0)
    └── framework-audit-hook.js (adapted per project)

Database (MongoDB)
├── governanceRules (enhanced with scope, variables)
├── projects
├── projectRules (overrides)
├── templates
├── sessions (concurrent session support)
├── sessionState
├── tokenCheckpoints
└── governanceAuditLogs (NEW - platform-wide audit trail)

Deployment System (NEW)
├── Unified deploy.sh script
├── .rsyncignore security exclusions
├── Cache busting (DEPLOYMENT_VERSION)
└── Security checks (localStorage, multi-tenant, credentials)

---

🗂️ Enhanced Database Schemas

NEW: governanceAuditLogs Collection

Purpose: Platform-wide governance decision tracking (tenant-aware, not filtered)

{
  _id: ObjectId("..."),
  sessionId: "claude-code-abc-123",

  // Framework service
  service: "BoundaryEnforcer",  // Enum: 6 services
  action: "boundary_enforcement",
  timestamp: ISODate("2025-11-02T10:30:00Z"),

  // Tenant context (for awareness, NOT filtering)
  tenantId: ObjectId("..."),  // Optional - null for platform-wide

  // Decision details
  decision: {
    allowed: Boolean,
    blocked: Boolean,
    requiresHuman: Boolean,
    confidence: Number,  // 0.0 - 1.0
    level: String        // CRITICAL | WARNING | INFO
  },

  // Context
  context: {
    sessionId: String,
    trigger: String,     // "hook" | "manual" | "scheduled"
    tool: String,        // "Edit" | "Write" | "Bash"
    actionDescription: String
  },

  // Metadata
  metadata: Map,         // Service-specific data
  boundaries: [String],  // Tractatus boundaries violated
  rulesChecked: [String],
  rulesViolated: [String],

  // User context
  userId: ObjectId("..."),

  // Multi-service coordination
  servicesInvolved: [String],
  frameworkBacked: Boolean,

  // Indexes
  indexes: [
    { sessionId: 1, timestamp: -1 },
    { service: 1, timestamp: -1 },
    { tenantId: 1, timestamp: -1 },  // For tenant-aware queries
    { timestamp: 1, expireAfterSeconds: 31536000 }  // 1 year TTL
  ]
}

Static Methods:

// Log a governance decision
GovernanceAuditLog.logDecision(data)

// Get session decisions
GovernanceAuditLog.getSessionDecisions(sessionId, limit)

// Get service decisions
GovernanceAuditLog.getServiceDecisions(service, { limit, since, tenantId })

// Get decisions requiring human judgment
GovernanceAuditLog.getHumanRequiredDecisions({ limit, since, tenantId, resolved })

Action Types (Constants):

GovernanceAuditLog.ACTIONS = {
  // BoundaryEnforcer
  BOUNDARY_ENFORCEMENT: 'boundary.enforcement',
  BOUNDARY_VIOLATION: 'boundary.violation',
  HUMAN_REQUIRED: 'boundary.human_required',

  // CrossReferenceValidator
  VALIDATION_CHECK: 'validation.check',
  VALIDATION_CONFLICT: 'validation.conflict',
  VALIDATION_PASS: 'validation.pass',

  // MetacognitiveVerifier
  REASONING_VERIFICATION: 'reasoning.verification',
  REASONING_ISSUE: 'reasoning.issue',

  // ContextPressureMonitor
  PRESSURE_ANALYSIS: 'pressure.analysis',
  PRESSURE_WARNING: 'pressure.warning',
  PRESSURE_CRITICAL: 'pressure.critical',

  // InstructionPersistenceClassifier
  INSTRUCTION_CLASSIFY: 'instruction.classify',
  INSTRUCTION_PERSIST: 'instruction.persist',

  // PluralisticDeliberationOrchestrator
  CONFLICT_ANALYSIS: 'conflict.analysis',
  DELIBERATION_REQUIRED: 'conflict.deliberation_required'
}

Enhanced governanceRules Collection

(Same as v1, with clarification on scope)

Scope Values:

• UNIVERSAL: Applies to all projects, contains variables
• PROJECT_SPECIFIC: Unique to one project, no variables (or project-specific values)

Example Universal Rule:

{
  id: "univ_001",
  scope: "UNIVERSAL",
  text: "Database connections MUST use ${DB_TYPE} on port ${DB_PORT}",
  variables: ["DB_TYPE", "DB_PORT"],
  applicableProjects: "*",
  // ... rest of fields
}

Example Project-Specific Rule:

{
  id: "fh_sec_001",
  scope: "PROJECT_SPECIFIC",
  text: "TenantStorage MUST be used for client-side storage. localStorage is strictly prohibited.",
  variables: [],
  applicableProjects: ["family-history"],
  // ... rest of fields
}

projects, projectRules, templates, sessions, sessionState, tokenCheckpoints Collections

(Same as v1 - see original plan for full schemas)

---

🚀 Revised Implementation Phases

Total Estimated Time: 50-62 hours (updated with new phases)

---

PHASE 0: Hook System Foundation ⭐ NEW - HIGH PRIORITY

Goal: Establish automatic governance enforcement via PreToolUse hooks

Duration: 2-3 hours

Why Phase 0: Hooks are the killer feature. They demonstrate immediate value and provide foundation for all other governance work.

0.1 Import Hook System (1 hour)

Tasks:

• Copy .claude/hooks/ directory from Tractatus to target project
  • framework-audit-hook.js (main hook - adapt for project)
  • all-command-detector.js
  • behavioral-compliance-reminder.js
  • check-token-checkpoint.js
  • trigger-word-checker.js
  • Other supporting hooks
• Adapt framework-audit-hook.js for target project
  • Update MongoDB connection string
  • Update database name
  • Update port if different
  • Change AuditLog.model → GovernanceAuditLog
• Test hook independently: node .claude/hooks/framework-audit-hook.js < test-input.json

Adaptation Checklist:

// framework-audit-hook.js changes
Line ~146: await mongoose.connect('mongodb://localhost:PORT/DB_NAME')
Line ~80:  const GovernanceAuditLog = require('../../src/models/GovernanceAuditLog')

Files Modified:

• .claude/hooks/framework-audit-hook.js

Success Criteria:

• Hook executes without errors
• Connects to correct MongoDB
• Logs to GovernanceAuditLog (if available)

---

0.2 Configure Hook Activation (0.5 hour)

Tasks:

• Update .claude/settings.local.json
  • Add hooks section
  • Configure SessionStart hook (optional)
  • Configure PreToolUse hooks for Edit/Write
• Test configuration
  • Restart Claude Code session
  • Verify hooks load
  • Check for errors in Claude Code output

Configuration:

{
  "permissions": { ... },
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/scripts/session-init.js"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/framework-audit-hook.js",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Files Modified:

• .claude/settings.local.json

Success Criteria:

• Hooks configured correctly
• SessionStart hook runs (if configured)
• PreToolUse hooks trigger on Edit/Write

---

0.3 Create GovernanceAuditLog Model (0.5 hour)

Tasks:

• Create src/models/GovernanceAuditLog.js
  • Define schema (see Enhanced Database Schemas above)
  • Add indexes
  • Add static methods
  • Add action constants
• Test model
  • Create test entry
  • Query entries
  • Verify indexes work

Files Created:

• src/models/GovernanceAuditLog.js

Success Criteria:

• Model creates without errors
• Can log governance decisions
• Queries work efficiently

---

0.4 Test Hook Integration (0.5 hour)

Tasks:

• Manual testing
  • Edit a file via Claude Code
  • Verify hook intercepts
  • Check for systemMessage feedback
  • Verify decision logged to GovernanceAuditLog
• Test with violations
  • Try to edit sensitive file
  • Verify hook blocks (if configured)
  • Check error handling
• Test with allowed operations
  • Edit normal file
  • Verify hook allows
  • Check audit log entry

Validation Queries:

// Check governance audit logs
db.governance_audit_logs.find().sort({timestamp:-1}).limit(10).pretty()

// Check for hook decisions
db.governance_audit_logs.find({ service: 'PreToolUseHook' })

// Check for blocks
db.governance_audit_logs.find({ 'decision.blocked': true })

Success Criteria:

• Hook intercepts Edit/Write operations
• Framework services validate actions
• Decisions logged correctly
• systemMessage provides feedback to Claude

---

0.5 Documentation (0.5 hour)

Tasks:

• Create docs/HOOK_SYSTEM_GUIDE.md
  • What hooks do
  • How to configure
  • How to test
  • Troubleshooting
• Update project README
  • Mention hook system
  • Link to guide

Files Created:

• docs/HOOK_SYSTEM_GUIDE.md

Files Modified:

• README.md

Success Criteria:

• Documentation is clear
• Easy to troubleshoot issues
• Next developer can understand system

---

Phase 0 Summary:

After Phase 0, the project has:

• ✅ Automatic governance enforcement via hooks
• ✅ GovernanceAuditLog tracking all decisions
• ✅ Real-time feedback to Claude Code
• ✅ Foundation for all other governance work

Estimated Time: 2-3 hours Actual Time (Family-History): 1 hour (hook import + config only, GovernanceAuditLog was Phase 2)

---

PHASE 1: Core Rule Manager UI (8-10 hours)

(Same as v1 - see original plan for full details)

Goal: Build foundational rule management interface with CRUD operations

1.1 Backend - Enhanced Rule Model (1 hour)

1.2 Backend - Rule Management API (2 hours)

1.3 Frontend - Rule Manager Dashboard (3 hours)

1.4 Frontend - Rule Editor Modal (2.5 hours)

1.5 Testing & Polish (1.5 hours)

---

PHASE 2: AI Rule Optimizer & CLAUDE.md Analyzer (10-12 hours)

(Same as v1 - see original plan)

Goal: Add intelligent rule optimization and CLAUDE.md migration

2.1 Backend - Rule Optimizer Service (3 hours)

2.2 Backend - CLAUDE.md Analyzer Service (3 hours)

2.3 Backend - API Endpoints for Optimization (1 hour)

2.4 Frontend - AI Optimization UI (3 hours)

2.5 Frontend - CLAUDE.md Migration Wizard (2 hours)

2.6 Testing & Validation (1 hour)

---

PHASE 3: Multi-Project Infrastructure (10-12 hours)

(Same as v1, with minor updates)

Goal: Enable management of multiple projects with variable substitution

3.1 Backend - Project Model & API (3 hours)

3.2 Backend - Rule Interpolator Service (2 hours)

3.3 Backend - Seed Initial Projects (1 hour)

3.4 Frontend - Project Switcher (1 hour)

3.5 Frontend - Project Manager Dashboard (2.5 hours)

3.6 Frontend - Project Configuration Editor (2.5 hours)

3.7 Testing & Integration (1 hour)

---

PHASE 3.5: Concurrent Session Architecture ✅ PARTIALLY IMPLEMENTED

Goal: Enable multiple concurrent Claude Code sessions without state contamination

Duration: 4-6 hours (original estimate) Status: Partially implemented in Family-History

What Was Implemented:

• ✅ GovernanceAuditLog provides session isolation
• ✅ session-init.js creates session in MongoDB
• ✅ framework-stats.js reads from MongoDB
• ✅ Session-specific metrics tracked

What Remains:

• ⏳ Full Session, SessionState, TokenCheckpoint models
• ⏳ SessionManager service
• ⏳ Update all framework services for session awareness
• ⏳ Concurrent session tests

3.5.1 Backend - Session Models (1 hour)

Tasks:

• Create src/models/Session.model.js
  • Full schema (see v1 plan)
  • Static methods
  • Instance methods
  • Indexes
• Create src/models/SessionState.model.js
  • Active instructions per session
  • Validations per session
  • Errors per session
• Create src/models/TokenCheckpoint.model.js
  • Checkpoint tracking
  • Framework fade detection

Files Created:

• src/models/Session.model.js
• src/models/SessionState.model.js
• src/models/TokenCheckpoint.model.js

Success Criteria:

• Models created with proper schemas
• Indexes configured
• Can create/query sessions

---

3.5.2 Backend - SessionManager Service (1.5 hours)

Tasks:

• Create src/services/SessionManager.service.js
  • initializeSession(projectId, purpose)
  • getSessionMetrics(sessionId)
  • updateSessionActivity(sessionId, data)
  • recordPressureCheckpoint(sessionId, tokens, pressure)
  • addInstruction(sessionId, instruction)
  • recordValidation(sessionId, validation)
  • completeSession(sessionId, reason)
  • cleanupOldSessions(daysOld)

Files Created:

• src/services/SessionManager.service.js

Success Criteria:

• Can create isolated sessions
• Metrics are session-specific
• No contamination between sessions

---

3.5.3 Scripts - Update Session Scripts (1 hour)

Tasks:

• Update scripts/session-init.js
  • ✅ Already creates session in MongoDB (family-history)
  • Add SessionState initialization
  • Add TokenCheckpoint initialization
• Update scripts/check-session-pressure.js
  • Read from MongoDB (not file)
  • Calculate session-specific pressure
• Create scripts/list-active-sessions.js
  • Query MongoDB for active sessions
  • Display session details

Files Modified:

• scripts/session-init.js
• scripts/check-session-pressure.js

Files Created:

• scripts/list-active-sessions.js

Success Criteria:

• Session initialization uses database
• Pressure checks use isolated metrics
• Can list all active sessions

---

3.5.4 Framework Integration (1 hour)

Tasks:

• Update src/services/ContextPressureMonitor.service.js
  • ✅ Already accepts sessionId (family-history)
  • Load metrics from MongoDB
  • Update metrics to MongoDB
• Update other services for session awareness
  • InstructionPersistenceClassifier
  • MetacognitiveVerifier
  • CrossReferenceValidator

Files Modified:

• All framework services

Success Criteria:

• All services session-aware
• Shared state uses file locking
• Isolated state uses MongoDB

---

3.5.5 Testing (0.5 hour)

Tasks:

• Create tests/integration/concurrent-sessions.test.js
  • Test isolated metrics
  • Test independent pressure calculations
  • Test shared instruction history
  • Test concurrent execution

Success Criteria:

• All concurrency tests pass
• No metric contamination
• Sessions can run simultaneously

---

Phase 3.5 Summary:

After Phase 3.5:

• ✅ Multiple Claude Code sessions can run concurrently
• ✅ Each session has isolated metrics
• ✅ Shared instruction history accessible to all
• ✅ No database conflicts

Estimated Time: 4-6 hours Partial Implementation (Family-History): ~1 hour (session-init.js + GovernanceAuditLog)

---

PHASE 4: Rule Validation Engine & Testing (8-10 hours)

(Same as v1)

Goal: Real-time rule validation using Tractatus framework services

4.1 Backend - Rule Validator Service (4 hours)

4.2 Backend - Validation API Endpoints (1 hour)

4.3 Frontend - Rule Validation UI (3 hours)

4.4 Integration Tests for Validator (2 hours)

4.5 Testing & Polish (1 hour)

---

PHASE 5: Project Templates & Cloning (6-8 hours)

(Same as v1)

Goal: Rapid project creation via templates and cloning

5.1 Backend - Template Model & Service (2 hours)

5.2 Backend - Template & Cloning API (1 hour)

5.3 Backend - Seed Templates (1 hour)

5.4 Frontend - New Project Wizard (2.5 hours)

5.5 Frontend - Template Library Page (1 hour)

5.6 Testing & Validation (0.5 hour)

---

PHASE 6: Deployment Modernization ⭐ NEW - HIGH VALUE

Goal: Replace ad-hoc deployment scripts with unified, secure system

Duration: 3-4 hours

Why High Priority: Replaces potentially hundreds of scripts with one intelligent script. Provides immediate, tangible value.

Family-History Impact: Replaced 134 scripts with 1 unified script

6.1 Analyze Existing Deployment (0.5 hour)

Tasks:

• Inventory existing deployment scripts
  • Count total scripts
  • Identify patterns
  • Find inconsistencies
  • Note security issues
• Document current deployment flow
  • What gets deployed
  • Where it goes
  • How cache busting works (if any)
  • Service restart process

Analysis Questions:

• How many deployment scripts exist?
• Are they consistent or ad-hoc?
• Is there cache busting?
• Are there security checks?
• What's the error handling?

Success Criteria:

• Understand current state
• Identify pain points
• Know what to preserve/improve

---

6.2 Create Unified Deployment Script (1.5 hours)

Tasks:

• Create scripts/deploy.sh
  • Parse arguments (files or --frontend-only)
  • 6-step deployment process:
    1. Pre-deployment checks
    2. Cache version update
    3. Git status review
    4. Deployment confirmation
    5. Deploy to production
    6. Post-deployment (restart/health check)
  • Security checks
    • Multi-tenant safety (if applicable)
    • localStorage violations (if applicable)
    • Local testing verification
    • Uncommitted changes warning
  • Features
    • Dry-run mode (--dry-run)
    • Automatic cache busting
    • Smart restart detection
    • Health checks
    • Template cleanup (if applicable)

Script Structure:

#!/bin/bash
set -e

# Configuration
REMOTE_USER="ubuntu"
REMOTE_HOST="example.com"
REMOTE_PATH="/var/www/app"
TIMESTAMP=$(date +%s)

# Parse flags
FILES_TO_DEPLOY=()
DRY_RUN=false
RESTART_SERVICE=false

# [1/6] PRE-DEPLOYMENT CHECKS
# - Project root verification
# - Security checks (project-specific)
# - Local server running
# - Uncommitted changes

# [2/6] CACHE VERSION UPDATE
# - Update service worker version
# - Generate DEPLOYMENT_VERSION timestamp

# [3/6] GIT STATUS
# - Show recent commits
# - Show uncommitted changes
# - Confirm to proceed

# [4/6] DEPLOYMENT CONFIRMATION
# - Show files to deploy
# - Show destination
# - Confirm to proceed

# [5/6] DEPLOY TO PRODUCTION
# - Deploy service worker first
# - Deploy requested files (or frontend)
# - Update DEPLOYMENT_VERSION on server

# [6/6] POST-DEPLOYMENT
# - Restart service if needed
# - Health check
# - Success message

Family-History Example:

# Deploy specific files
./scripts/deploy.sh public/js/gallery-modern.js

# Deploy multiple files with restart
./scripts/deploy.sh src/controllers/chatController.js public/js/chat.js --restart

# Dry-run preview
./scripts/deploy.sh public/js/file.js --dry-run

# Deploy frontend only
./scripts/deploy.sh --frontend-only

Files Created:

• scripts/deploy.sh

Success Criteria:

• Script handles all deployment scenarios
• Security checks prevent bad deployments
• Cache busting works
• Dry-run shows accurate preview
• Health checks verify success

---

6.3 Create Security Exclusions (0.5 hour)

Tasks:

• Create .rsyncignore for full deployment
  • Sensitive configuration (.env, .env.*)
  • Credentials (*.key, *.pem, credentials.json)
  • Governance files (CLAUDE.md, .claude/, docs/)
  • Development tools (.vscode/, node_modules/)
  • Logs (*.log, logs/)
  • Testing (test/, *.test.js)
  • OS files (.DS_Store, Thumbs.db)
• Document exclusions
  • Why each pattern is excluded
  • Reference to governance rules

Example .rsyncignore:

# Sensitive configuration
.env
.env.*
!.env.production

# Credentials
*.key
*.pem
credentials.json
secrets.json

# Governance files (inst_XXX reference)
CLAUDE.md
.claude/
TRACTATUS_INTEGRATION_PLAN.md

# Development tools
.vscode/
.idea/
node_modules/

# Testing
test/
tests/
*.test.js
coverage/

# Logs
*.log
logs/

# OS files
.DS_Store
Thumbs.db

Files Created:

• .rsyncignore

Success Criteria:

• Sensitive files excluded
• Deployment is secure
• No accidental credential leaks

---

6.4 Test Deployment Script (0.5 hour)

Tasks:

• Test with dry-run
  • Deploy single file
  • Deploy multiple files
  • Deploy frontend only
  • Verify preview is accurate
• Test security checks
  • Trigger localStorage violation (if applicable)
  • Try without local testing
  • Deploy with uncommitted changes
• Test actual deployment
  • Deploy to staging (if available)
  • Verify files transferred
  • Verify cache bust works
  • Verify restart works
  • Check health endpoint

Test Checklist:

• Dry-run shows correct files
• Security checks block bad deployments
• Cache busting generates new version
• Service restarts when needed
• Health check verifies success
• Error handling is clear

Success Criteria:

• Script works in all scenarios
• No bugs in deployment flow
• Clear feedback at each step

---

6.5 Documentation & Migration (0.5 hour)

Tasks:

• Create docs/DEPLOYMENT_GUIDE.md
  • How to use new script
  • Examples for common scenarios
  • Troubleshooting
  • Comparison with old scripts
• Update project README
  • Deployment section
  • Link to guide
• Deprecation plan for old scripts
  • Move to scripts/deprecated/
  • Add README explaining deprecation
  • Keep for reference

Deprecation README Example:

# Deprecated Deployment Scripts

These scripts have been replaced by `scripts/deploy.sh`.

## Migration Guide

Old: `./scripts/deploy-dashboard-fix.sh`
New: `./scripts/deploy.sh public/js/dashboard.js`

Old: `./scripts/deploy-api-emergency.sh`
New: `./scripts/deploy.sh src/controllers/*.js --restart`

See `docs/DEPLOYMENT_GUIDE.md` for full documentation.

Files Created:

• docs/DEPLOYMENT_GUIDE.md
• scripts/deprecated/README.md

Files Modified:

• README.md

Success Criteria:

• Documentation is comprehensive
• Easy to migrate from old scripts
• Deprecation plan is clear

---

Phase 6 Summary:

After Phase 6:

• ✅ Unified deployment script replaces all ad-hoc scripts
• ✅ Security checks prevent bad deployments
• ✅ Cache busting forces browser refresh
• ✅ Dry-run capability
• ✅ Health checks verify success
• ✅ Clear documentation

Estimated Time: 3-4 hours Actual Time (Family-History): 2 hours

Value Delivered:

• Replaced 134 scripts with 1 (if similar to family-history)
• Consistent deployment process
• Security enforcement
• Developer experience improvement

---

PHASE 7: Polish, Documentation & Production (4-6 hours)

(Updated from v1 "Phase 6")

Goal: Production-ready system with comprehensive documentation

7.1 UI/UX Polish (2 hours)

7.2 Documentation (2 hours)

7.3 Security Audit (1 hour)

7.4 Performance Optimization (0.5 hour)

7.5 Production Deployment (0.5 hour)

---

📋 Integration Patterns (NEW Section)

Pattern 1: Framework Service Adaptation

When: Integrating Tractatus services into new project

Steps:

1. Copy service files to src/services/
2. Update MongoDB connection string
3. Make MemoryProxy optional (if not needed)
4. Add tenant context (if multi-tenant)
5. Update logger path
6. Test service initialization

Code Template:

// At top of service file
const logger = require('../utils/logger');
const { getCurrentTenant } = require('../utils/tenantContext'); // If multi-tenant
const GovernanceAuditLog = require('../models/GovernanceAuditLog');

// In initialize() method
async initialize(sessionId) {
  this.sessionId = sessionId;

  // Optional: Make MemoryProxy optional
  this.memoryProxy = null;  // Or getMemoryProxy() if available

  // Connect to MongoDB with project-specific port/database
  await mongoose.connect('mongodb://localhost:PORT/DATABASE_NAME');
}

// In audit method
_auditDecision(result, action, context = {}) {
  const tenantId = getCurrentTenant();  // null if not multi-tenant

  GovernanceAuditLog.logDecision({
    tenantId,
    service: 'ServiceName',
    // ... rest of audit data
  });
}

Time Estimate: 2-3 hours for all 6 services

---

Pattern 2: Hook System Setup

When: Adding automatic governance enforcement

Steps:

1. Copy .claude/hooks/ directory
2. Adapt framework-audit-hook.js for project
3. Create GovernanceAuditLog model (if not exists)
4. Configure .claude/settings.local.json
5. Test hook activation

Configuration Template:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/framework-audit-hook.js",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Time Estimate: 1 hour

---

Pattern 3: Multi-Tenant Governance

When: Project has multi-tenant architecture

Components:

1. AsyncLocalStorage for tenant context
2. GovernanceAuditLog (tenant-aware, not filtered)
3. AuditLog (tenant-filtered)
4. Framework services call getCurrentTenant()

Architecture:

Request → tenantContextMiddleware → AsyncLocalStorage
              ↓
         Framework Services
              ↓
         getCurrentTenant()
              ↓
         GovernanceAuditLog (records tenantId for context)

Time Estimate: 2-3 hours

---

Pattern 4: Deployment Modernization

When: Project has many ad-hoc deployment scripts

Steps:

1. Analyze existing scripts (count, patterns)
2. Create unified deploy.sh script
3. Add security checks (project-specific)
4. Create .rsyncignore for exclusions
5. Test with dry-run
6. Deprecate old scripts

Features to Include:

• Dry-run mode
• Cache busting (timestamp-based)
• Security checks (localStorage, credentials, etc.)
• Smart restart detection
• Health checks

Time Estimate: 3-4 hours

---

Pattern 5: Session Management

When: Supporting concurrent Claude Code sessions

Components:

1. Session model (unique ID, metrics, status)
2. SessionState model (active instructions, validations)
3. TokenCheckpoint model (pressure tracking)
4. SessionManager service (CRUD operations)
5. Updated framework services (session-aware)

Key Insight: GovernanceAuditLog provides session isolation automatically (via sessionId field)

Time Estimate: 4-6 hours (or 1 hour for basic version)

---

📊 Updated Summary

Total Estimated Time: 50-62 hours

Phase	Estimated Time	Status	Key Deliverables
Phase 0: Hook System	2-3 hours	✅ Validated	Automatic governance enforcement
Phase 1: Core Rule Manager	8-10 hours	⏳ Planned	Rule CRUD, dashboard, editor
Phase 2: AI Optimizer	10-12 hours	⏳ Planned	Rule optimization, CLAUDE.md migration
Phase 3: Multi-Project	10-12 hours	⏳ Planned	Project management, variable interpolation
Phase 3.5: Concurrent Sessions	4-6 hours	🔄 Partial	Database-backed session state
Phase 4: Validation Engine	8-10 hours	⏳ Planned	Real-time rule validation
Phase 5: Templates & Cloning	6-8 hours	⏳ Planned	Project templates, cloning
Phase 6: Deployment	3-4 hours	✅ Validated	Unified deployment script
Phase 7: Polish & Production	4-6 hours	⏳ Planned	Documentation, security, deployment

Milestones (Updated)

Milestone 0 (After Phase 0): ✅ Hook system operational - VALIDATED Milestone 1 (After Phase 1): Basic rule management working Milestone 2 (After Phase 2): AI-powered optimization and CLAUDE.md migration Milestone 3 (After Phase 3): Multi-project system operational Milestone 3.5 (After Phase 3.5): 🔄 Concurrent session support (partially validated) Milestone 4 (After Phase 4): Validation engine integrated Milestone 5 (After Phase 5): Template system complete Milestone 6 (After Phase 6): ✅ Deployment modernized - VALIDATED Milestone 7 (After Phase 7): Production-ready, world-class system

---

🎯 Updated Success Criteria

Product is ready when:

• Hook system enforces governance automatically (✅ Validated)
• GovernanceAuditLog tracks all decisions (✅ Validated)
• Deployment modernized with security checks (✅ Validated)
• All rules managed via UI
• CLAUDE.md successfully migrated to rules
• Can manage multiple projects (Tractatus + others)
• Rules validated against framework in real-time
• Can create projects from templates in <2 minutes
• AI optimizer improves rule clarity measurably
• Documentation is comprehensive
• No security vulnerabilities
• Deployed to production and stable

Commercialization Ready When:

• System is polished and professional
• Documentation suitable for external users
• Multi-tenant support (user authentication/authorization)
• Pricing/billing system (if SaaS)
• Marketing materials prepared
• Support system in place
• Integration guides for common stacks
• Video tutorials/demos
• Customer testimonials/case studies

---

🔍 Validation Evidence

Family-History Integration (Nov 1-2, 2025)

Validated Phases:

• ✅ Phase 0: Hook System (1 hour actual)
• ✅ Phase 6: Deployment Modernization (2 hours actual)
• 🔄 Phase 3.5: Concurrent Sessions (1 hour partial)

Validated Patterns:

• ✅ Framework Service Adaptation (2 hours for 6 services)
• ✅ Multi-Tenant Governance (GovernanceAuditLog + AsyncLocalStorage)
• ✅ Hook System Setup (framework-audit-hook.js)
• ✅ Deployment Modernization (unified deploy.sh)

Evidence:

• Session handoff: docs/session-handoffs/session-handoff-2025-11-02-tractatus-framework-deployment.md
• GovernanceAuditLog model: src/models/GovernanceAuditLog.js (261 lines)
• Deployment script: scripts/deploy.sh (400 lines)
• Hook system: .claude/hooks/framework-audit-hook.js (adapted)
• All 6 framework services updated with tenant context

Metrics:

• Integration time: ~8 hours total
• Scripts replaced: 134 → 1
• Governance rules: 31 active
• Framework services: 6 active
• Zero runtime errors

---

🚦 Next Steps

Immediate Actions (Priority Order)

1. ✅ Document Family-History Integration (COMPLETE)

   • Session handoff created
   • Lessons learned documented
   • Integration patterns validated

2. Review This Updated Plan

   • Confirm Phase 0 priority
   • Validate Phase 6 inclusion
   • Approve architectural updates

3. Choose Next Phase

   • Option A: Begin Phase 1 (Core Rule Manager UI)
   • Option B: Complete Phase 3.5 (Concurrent Sessions)
   • Option C: Begin Phase 2 (AI Optimizer) for CLAUDE.md migration

4. Set Up Project Tracking

   • Create task board
   • Break down chosen phase
   • Estimate timeline

Recommended Sequence

Based on value delivered and validation:

1. Phase 0 - Hook System (if not yet integrated) ⭐ Highest ROI
2. Phase 6 - Deployment Modernization (if many scripts exist) ⭐ Quick Win
3. Phase 1 - Core Rule Manager UI (foundation for everything)
4. Phase 2 - AI Optimizer (CLAUDE.md migration is valuable)
5. Phase 3 - Multi-Project Infrastructure
6. Phase 3.5 - Concurrent Sessions (finish what was started)
7. Phase 4 - Validation Engine
8. Phase 5 - Templates & Cloning
9. Phase 7 - Polish & Production

Questions to Resolve

1. Calendar Review Date: When is the Tractatus calendar review?
2. Multi-Project Priority: How many projects will use this system?
3. Commercial Timeline: When do you want to commercialize?
4. Phase Selection: Which phase should we start with?
5. Time Commitment: How many hours/week can you dedicate?

---

📚 References

Internal Documentation

• Family-History Session Handoff: family-history/docs/session-handoffs/session-handoff-2025-11-02-tractatus-framework-deployment.md
• Concurrent Session Architecture: tractatus/docs/research/concurrent-session-architecture-limitations.md
• Original Implementation Plan v1: tractatus/docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md

Models & Services

• GovernanceAuditLog: src/models/GovernanceAuditLog.js
• All 6 Framework Services: src/services/*Enforcer|*Validator|*Verifier|*Monitor|*Classifier|*Orchestrator*.service.js
• SessionManager (planned): src/services/SessionManager.service.js

Scripts & Tools

• Hook System: .claude/hooks/framework-audit-hook.js
• Session Init: scripts/session-init.js
• Framework Stats: scripts/framework-stats.js
• Deployment: scripts/deploy.sh (family-history example)

External References

• AsyncLocalStorage: https://nodejs.org/api/async_context.html
• MongoDB Indexes: https://docs.mongodb.com/manual/indexes/
• PreToolUse Hooks: Claude Code documentation

---

🎓 Appendix: Architectural Decisions

Why GovernanceAuditLog is Separate from AuditLog

Problem: Multi-tenant projects need both user action auditing (tenant-isolated) and governance decision auditing (platform-wide).

Solution:

• AuditLog: Tenant-filtered, stores user actions within a tenant
• GovernanceAuditLog: Platform-wide, tenant-aware, stores framework decisions

Rationale:

1. Legal Compliance: User audit logs must be tenant-isolated for privacy
2. Security Analytics: Governance logs must be platform-wide to detect patterns
3. Performance: Separate collections prevent tenant-filter overhead on governance queries
4. Clarity: Clear separation of concerns

Alternative Considered: Single audit log with optional tenant filter Rejected Because: Mixing governance and user actions is semantically incorrect

---

Why Hooks are Phase 0

Original Plan: Hooks not mentioned until implementation details

Problem: Hooks are the most valuable feature, demonstrate immediate ROI

Solution: Promote to Phase 0 (foundation)

Rationale:

1. Immediate Value: Automatic governance enforcement from day 1
2. Demonstrates Power: Shows framework value quickly
3. Foundation: Other features build on hook-enforced governance
4. Sales: Best feature for commercialization pitch

Evidence: Family-History integration put hooks first, validated approach

---

Why Deployment Modernization is a Phase

Original Plan: No deployment phase

Problem: Ad-hoc deployment scripts are pain point, modernization delivers value

Solution: Add Phase 6 (Deployment Modernization)

Rationale:

1. Pain Point: Projects often have 50-100+ ad-hoc scripts
2. Security: Unified script can enforce security checks
3. Consistency: One script ensures repeatable deployments
4. Developer Experience: Massive improvement in usability

Evidence: Family-History had 134 scripts, replaced with 1, huge win

---

Version: 2.0 Last Updated: November 2, 2025 Status: Ready for Implementation Validated: Family-History Integration (Nov 2025)

---

Ready to build the future of AI-powered governance? 🚀