tractatus/FAMILY_HISTORY_FRAMEWORK_INTEGRATION_PLAN.md

# Family-History Framework Integration Plan

**Project:** family-history (Multi-Tenant Family History SaaS)
**Source:** Tractatus Governance Framework
**Plan Date:** 2025-11-01
**Status:** Phase 1 - Planning Complete, Ready for Implementation

---

## 📋 Executive Summary

This plan outlines the integration of the **Tractatus Governance Framework** into the family-history project, a production multi-tenant SaaS platform (myfamilyhistory.digital).

### Value Proposition

**Immediate gains (41 rules):**
- World-class development standards
- Security best practices (CSP, secret detection, input validation)
- Deployment checklists and quality gates
- Git conventions and testing strategies

**Framework installation unlocks (13 additional rules):**
- Session pressure monitoring (token budget management)
- Boundary enforcement (prohibited terms, values conflicts)
- Audit logging (governance decision tracking)
- Cross-reference validation (architectural consistency)
- Metacognitive verification (quality assurance)

**Total governance coverage:** 54 applicable rules (79.4% of Tractatus rules)

---

## 🏗️ Architecture Overview

### family-history Project Profile

**Scale & Complexity:**
- **Codebase:** 191,484 lines of JavaScript
- **Database:** MongoDB on port 27027 (70+ Mongoose models)
- **Architecture:** Multi-tenant SaaS with AsyncLocalStorage tenant isolation
- **Features:** Email integration (Proton Bridge), dual-language translation (DeepL), GDPR compliance, worker system
- **Deployment:** OVHCloud VPS, systemd service management
- **Production:** https://myfamilyhistory.digital/ (Stroh family tenant in beta)
- **Development:** http://localhost:7000/

### Tractatus Framework Components

**Six Core Services:**
1. **ContextPressureMonitor** - Token budget & session management
2. **BoundaryEnforcer** - Values, security, prohibited terms
3. **CrossReferenceValidator** - Architectural consistency checks
4. **MetacognitiveVerifier** - Quality & reasoning verification
5. **InstructionPersistenceClassifier** - Rule lifecycle management
6. **PluralisticDeliberationOrchestrator** - Values conflict resolution

**Supporting Infrastructure:**
- Session management scripts (session-init.js, check-pressure.js, session-closedown.js)
- Instruction persistence (.claude/instruction-history.json)
- Audit logging system (MongoDB-backed)
- Hook validators (pre-action checks)

---

## 🎯 Three-Layer Rule System

### Layer 1: Development Environment Rules (4 rules extracted)

**From family-history CLAUDE.md:**
1. ✅ ALWAYS check latest session handoff before starting work
2. ✅ ALWAYS test locally on port 7000 before deployment
3. ✅ ALWAYS deploy with `./scripts/deploy-with-cache-bust.sh`
4. ⚠️ Session handoff must include specific metadata (needs clarification)

**Integration:** These become HIGH persistence, OPERATIONAL quadrant instructions in `.claude/instruction-history.json`

---

### Layer 2: Architectural Constraints (3 rules extracted)

**From family-history CLAUDE.md:**
1. ✅ **NEVER violate multi-tenant isolation** - all queries filter by tenantId
2. ✅ **All queries MUST filter by tenantId** (database layer enforcement)
3. ✅ **Never hardcode tenant IDs** (security boundary)

**Integration:** These become HIGH persistence, SYSTEM quadrant instructions, enforced by BoundaryEnforcer and CrossReferenceValidator

---

### Layer 3: Tenant Configuration (NOT governance rules)

**Clarification:** Product defaults for new tenants (e.g., "default language: English", "retention: 5 years") are **code constants**, not governance rules. These belong in:
- `src/models/Tenant.js` (Mongoose schema defaults)
- `src/config/tenant-defaults.js` (if extracted)

**Out of scope for framework integration.**

---

## 🔓 Unlocking 13 Blocked Rules

**Currently blocked Tractatus rules that will become applicable after framework installation:**

### Session Management (4 rules)
- `inst_006` - Use ContextPressureMonitor for session management
- `inst_019` - Account for total context window consumption
- `inst_038` - Pre-action checks before file edits
- `inst_075` - Token checkpoint enforcement at 50k/100k/150k

### Boundary Enforcement (3 rules)
- `inst_017` - Prohibited absolute assurance terms ("guarantee", "100%")
- `inst_049` - Test user hypotheses before proposing alternatives
- `inst_081` - Pluralism principle (values conflicts)

### Audit & Governance (3 rules)
- `inst_077` - Session closedown with audit analysis
- `inst_082` - Framework stats display ("ffs" command)
- `inst_091` - Framework evolution preserving audit logs

### Framework Integration (3 rules)
- `inst_039` - Content audit for values conflicts
- `inst_078` - Full framework audit trigger ("ff" command)
- `inst_083` - Session handoff extraction

---

## 🔧 Multi-Tenant Adaptation Requirements

### Critical Difference: Tractatus vs family-history

| Aspect | Tractatus | family-history | Adaptation Required |
|--------|-----------|----------------|---------------------|
| **Tenancy** | Single instance | Multi-tenant SaaS | ✅ HIGH |
| **Context Isolation** | File-based | AsyncLocalStorage | ✅ MEDIUM |
| **Database** | Simple MongoDB | Mongoose ODM (70+ models) | ✅ MEDIUM |
| **Sessions** | Single user | Concurrent tenants | ✅ HIGH |
| **Audit Logging** | Framework only | Framework + PrivacyAuditLog | ✅ MEDIUM |

### Adaptation Strategy

#### 1. Tenant Context Integration

**Challenge:** Framework services must respect tenant boundaries.

**Solution:**
```javascript
// Before (Tractatus - single tenant)
ContextPressureMonitor.check()

// After (family-history - multi-tenant aware)
const tenantContext = AsyncLocalStorage.getStore();
ContextPressureMonitor.check({ tenantId: tenantContext?.tenantId })
```

**Implementation:**
- Modify all 6 framework services to accept optional `tenantId` parameter
- Use AsyncLocalStorage to automatically inject tenant context
- Ensure audit logs include `tenantId` for cross-tenant isolation
- Validate that framework actions don't leak across tenants

#### 2. Session Management Adaptation

**Challenge:** Development sessions work on multi-tenant codebase, but session state is per-developer, not per-tenant.

**Solution:**
- Session state (`.claude/session-state.json`) remains developer-scoped
- Framework monitors **codebase health** across all tenants
- BoundaryEnforcer checks for tenant isolation violations
- Audit logs record which tenant context was active during operations

**Example:**
```javascript
// Session init detects multi-tenant project
await sessionInit({
  projectType: 'multi-tenant',
  tenantIsolationRequired: true,
  productionTenants: ['stroh'], // Active production tenants
  testTenant: 'test-tenant' // Development tenant
});
```

#### 3. Audit Log Integration

**Challenge:** family-history already has `PrivacyAuditLog` for GDPR compliance.

**Solution:** **Dual audit system:**
- **Framework audit logs** → MongoDB `audit_logs` collection (governance decisions)
- **Privacy audit logs** → Existing `PrivacyAuditLog` model (GDPR compliance)
- Both coexist, serve different purposes
- Framework can reference privacy logs when validating GDPR compliance

**Example:**
```javascript
// Framework audit log
await AuditLog.create({
  service: 'BoundaryEnforcer',
  decision: 'BLOCKED',
  reason: 'Multi-tenant isolation violation detected',
  action: 'Query missing tenantId filter',
  file: 'src/controllers/contributionController.js:45',
  sessionId: 'session-2025-11-01-001'
  // NO tenantId - this is framework governance, not tenant data
});

// Privacy audit log (existing)
await PrivacyAuditLog.create({
  tenantId: req.tenant._id,
  userId: req.user._id,
  action: 'ACCESS',
  resource: 'contribution',
  resourceId: contributionId,
  ipAddress: req.ip
  // HAS tenantId - this is GDPR compliance
});
```

---

## 📦 Portable Components from Tractatus

### Highly Portable (Copy + Adapt)

#### Framework Services
- ✅ `src/services/BoundaryEnforcer.service.js`
- ✅ `src/services/MetacognitiveVerifier.service.js`
- ✅ `src/services/CrossReferenceValidator.service.js`
- ✅ `src/services/ContextPressureMonitor.service.js`
- ✅ `src/services/InstructionPersistenceClassifier.service.js`
- ✅ `src/services/PluralisticDeliberationOrchestrator.service.js`

**Adaptation:** Add tenant context awareness (AsyncLocalStorage integration)

#### Session Management Scripts
- ✅ `scripts/session-init.js`
- ✅ `scripts/check-session-pressure.js`
- ✅ `scripts/session-closedown.js`
- ✅ `scripts/framework-audit-response.js`
- ✅ `scripts/framework-stats.js`

**Adaptation:** Update ports (9000→7000, 27017→27027), paths, project name

#### Instruction System
- ✅ `.claude/instruction-history.json` structure
- ✅ Quadrant classification (STRATEGIC/SYSTEM/OPERATIONAL/TACTICAL)
- ✅ Persistence levels (HIGH/MEDIUM/LOW)
- ✅ Temporal scope (PERMANENT/PROJECT/SESSION)

**Adaptation:** Create new instruction-history.json for family-history

#### Audit System
- ✅ `src/models/AuditLog.model.js`
- ✅ Audit analytics dashboard patterns
- ✅ Decision recording patterns

**Adaptation:** Integrate alongside existing PrivacyAuditLog

### Moderately Portable (Needs Review)

#### Hook Validators
- ⚠️ `scripts/hook-validators/validate-file-edit.js`
- ⚠️ `scripts/hook-validators/validate-file-write.js`
- ⚠️ `scripts/hook-validators/check-token-checkpoint.js`

**Challenge:** family-history may use different IDE/workflow than Tractatus
**Action:** Evaluate if Claude Code hooks apply, adapt or skip

### Not Portable (Tractatus-Specific)

- ❌ Public frontend (single-tenant UI)
- ❌ Document processing (glossary PDFs)
- ❌ Blog/case submission forms
- ❌ Tractatus-specific models

---

## 🚀 Implementation Roadmap

### Phase 1: Preparation (Complete - This Document)

**Deliverables:**
- ✅ CLAUDE.md extraction script (`scripts/analyze-claude-md.js`)
- ✅ Extracted rules from family-history CLAUDE.md (7 rules)
- ✅ Applicability analysis (54 applicable rules identified)
- ✅ This integration plan document

**Time:** 2-3 hours ✅ **COMPLETE**

---

### Phase 2: Infrastructure Setup (Next Session)

**Location:** Move to `/home/theflow/projects/family-history` directory

**Tasks:**

#### 2.1 SSL Certificate Renewal (1 hour)
- Audit current wildcard certificate for *.myfamilyhistory.digital
- Renew if expiring soon
- Test subdomain routing (stroh.myfamilyhistory.digital)
- Document renewal process for future

#### 2.2 Git/GitHub Assessment (1 hour)
- Audit current git configuration (local only, no GitHub)
- Evaluate GitHub migration value vs risk
- Document current state
- Decision: Migrate now or defer to later phase

#### 2.3 Backup System Audit (1 hour)
- Review BorgBackup configuration
- Test restore procedures
- Verify OVHCloud integration
- Document backup strategy

**Time:** 3 hours
**Risk:** Low - infrastructure maintenance, no code changes

---

### Phase 3: Framework Installation (Implementation Phase)

**Location:** `/home/theflow/projects/family-history` directory

#### 3.1 Directory Structure Setup (30 min)

```bash
cd /home/theflow/projects/family-history

# Create .claude directory
mkdir -p .claude
mkdir -p .claude/sessions
mkdir -p .claude/handoffs

# Create scripts directory structure
mkdir -p scripts/framework
mkdir -p scripts/hook-validators
```

**Deliverables:**
- `.claude/` directory structure
- `scripts/framework/` for framework scripts

#### 3.2 Copy Core Framework Services (1 hour)

```bash
# Copy 6 framework services
cp /home/theflow/projects/tractatus/src/services/BoundaryEnforcer.service.js \
   /home/theflow/projects/family-history/src/services/

cp /home/theflow/projects/tractatus/src/services/MetacognitiveVerifier.service.js \
   /home/theflow/projects/family-history/src/services/

cp /home/theflow/projects/tractatus/src/services/CrossReferenceValidator.service.js \
   /home/theflow/projects/family-history/src/services/

cp /home/theflow/projects/tractatus/src/services/ContextPressureMonitor.service.js \
   /home/theflow/projects/family-history/src/services/

cp /home/theflow/projects/tractatus/src/services/InstructionPersistenceClassifier.service.js \
   /home/theflow/projects/family-history/src/services/

cp /home/theflow/projects/tractatus/src/services/PluralisticDeliberationOrchestrator.service.js \
   /home/theflow/projects/family-history/src/services/
```

**Then adapt each service:**
- Update database connection (port 27027)
- Add tenant context awareness (AsyncLocalStorage)
- Update file paths and project names
- Test in isolation

#### 3.3 Adapt for Multi-Tenant Context (2 hours)

**All 6 services need this pattern:**

```javascript
// Add at top of each service
const { AsyncLocalStorage } = require('async_hooks');

class BoundaryEnforcer {
  constructor() {
    this.tenantStorage = AsyncLocalStorage;
  }

  async enforce(action, context = {}) {
    // Get current tenant context if available
    const tenantContext = this.tenantStorage.getStore();
    const tenantId = context.tenantId || tenantContext?.tenantId;

    // Log with tenant context
    await this.logDecision({
      ...decision,
      tenantId, // Include in audit log (but decision is project-wide)
      multiTenantProject: true
    });

    // Original enforcement logic...
  }
}
```

**Critical adaptations:**
1. **BoundaryEnforcer** - Add multi-tenant isolation checks
2. **CrossReferenceValidator** - Validate tenantId filtering patterns
3. **ContextPressureMonitor** - Session pressure is per-developer, not per-tenant
4. **MetacognitiveVerifier** - Verify tenant isolation in reasoning
5. **InstructionPersistenceClassifier** - Parse tenant-specific vs system-wide rules
6. **PluralisticDeliberationOrchestrator** - GDPR conflicts are cross-tenant

#### 3.4 Copy Session Management Scripts (1 hour)

```bash
# Copy session scripts
cp /home/theflow/projects/tractatus/scripts/session-init.js \
   /home/theflow/projects/family-history/scripts/

cp /home/theflow/projects/tractatus/scripts/check-session-pressure.js \
   /home/theflow/projects/family-history/scripts/

cp /home/theflow/projects/tractatus/scripts/session-closedown.js \
   /home/theflow/projects/family-history/scripts/

cp /home/theflow/projects/tractatus/scripts/framework-audit-response.js \
   /home/theflow/projects/family-history/scripts/

cp /home/theflow/projects/tractatus/scripts/framework-stats.js \
   /home/theflow/projects/family-history/scripts/
```

**Adapt configuration:**
- Update ports: 9000 → 7000 (dev), 8000 (prod)
- Update MongoDB port: 27017 → 27027
- Update database name: tractatus_dev → family_history
- Update project name in output messages
- Add multi-tenant project detection

**Example session-init.js changes:**
```javascript
// Old (Tractatus)
const DEV_PORT = 9000;
const MONGO_PORT = 27017;
const DB_NAME = 'tractatus_dev';

// New (family-history)
const DEV_PORT = 7000;
const MONGO_PORT = 27027;
const DB_NAME = 'family_history';
const MULTI_TENANT = true; // New flag
```

#### 3.5 Create instruction-history.json (1 hour)

```bash
# Initialize instruction history
cat > /home/theflow/projects/family-history/.claude/instruction-history.json << 'EOF'
{
  "version": "1.0",
  "last_updated": "2025-11-01T00:00:00Z",
  "description": "Persistent instruction database for family-history governance",
  "project": {
    "name": "family-history",
    "type": "multi-tenant-saas",
    "tenant_isolation": "MANDATORY"
  },
  "instructions": []
}
EOF
```

**Populate with:**
1. Layer 1 rules (4 from CLAUDE.md extraction)
2. Layer 2 rules (3 from CLAUDE.md extraction)
3. Applicable Tractatus rules (41 already-applicable rules)
4. Framework-unlocked rules (13 blocked rules, now applicable)

**Total:** ~61 initial instructions

#### 3.6 Create Audit Log Model (30 min)

```bash
# Copy audit log model
cp /home/theflow/projects/tractatus/src/models/AuditLog.model.js \
   /home/theflow/projects/family-history/src/models/
```

**Adapt schema:**
- Add `multiTenantProject: Boolean` field
- Add `activeTenantId` field (which tenant context was active during decision)
- Keep governance decisions separate from PrivacyAuditLog

**Example:**
```javascript
const auditLogSchema = new mongoose.Schema({
  // ... existing fields ...
  multiTenantProject: { type: Boolean, default: true },
  activeTenantId: { type: mongoose.Schema.Types.ObjectId, ref: 'Tenant' }, // Context only
  // NOTE: Governance decisions are project-wide, not tenant-specific
  // activeTenantId shows which tenant context was active during decision
});
```

#### 3.7 Integration Testing (2 hours)

**Test scenarios:**

1. **Framework Services Initialization**
   ```bash
   node scripts/session-init.js
   # Verify all 6 services initialize
   # Verify multi-tenant detection
   # Verify MongoDB connection (port 27027)
   ```

2. **Tenant Context Isolation**
   ```javascript
   // Test tenant context in AsyncLocalStorage
   const tenantContext = await tenantStorage.run({ tenantId: 'test-tenant' }, async () => {
     await BoundaryEnforcer.enforce('test-action');
     // Verify audit log includes activeTenantId
   });
   ```

3. **Multi-Tenant Boundary Enforcement**
   ```javascript
   // Test detection of missing tenantId filter
   const query = { contributionId: '123' }; // Missing tenantId
   await CrossReferenceValidator.validateQuery(query);
   // Should WARN: Query missing tenantId filter
   ```

4. **Session Pressure Monitoring**
   ```bash
   node scripts/check-session-pressure.js --tokens=50000/200000
   # Verify pressure calculation
   # Verify checkpoint reporting
   ```

5. **Audit Log Separation**
   ```javascript
   // Verify framework audit logs separate from privacy logs
   const frameworkLogs = await AuditLog.find({ service: 'BoundaryEnforcer' });
   const privacyLogs = await PrivacyAuditLog.find({ tenantId: 'test-tenant' });
   // Should be in different collections
   ```

**Time:** 8 hours (3.1-3.7 combined)
**Risk:** Medium - code changes, careful testing required

---

### Phase 4: CLAUDE.md Creation & Rule Import (Consolidation)

#### 4.1 Create family-history CLAUDE.md (1 hour)

**Approach:** Enhance existing CLAUDE.md, don't replace

**Current CLAUDE.md has:**
- 🚨 Critical rules (5 items)
- ⚡ System info (ports, credentials)
- 🚀 Session startup checklist
- 🔧 Essential commands
- ⚠️ Critical warnings
- 🔐 Multi-tenancy section
- 🏁 Session handoff requirements

**Add framework sections:**
```markdown
## 🎯 FRAMEWORK GOVERNANCE

### Mandatory Session Start
```bash
node scripts/session-init.js
```

### Framework Triggers
- Type **ff** - Full framework audit
- Type **ffs** - Framework statistics

### Token Checkpoints
- 50k tokens (25%) - Report pressure
- 100k tokens (50%) - Report pressure
- 150k tokens (75%) - Report pressure

### Prohibited Terms
- NEVER use: "guarantee", "100%", "ensures", "eliminates all"
- Use: "designed to", "helps reduce", "aims to"

### Multi-Tenant Isolation (CRITICAL)
- ALL database queries MUST filter by tenantId
- NEVER hardcode tenant IDs
- NEVER bypass tenant isolation middleware
- Framework enforces via CrossReferenceValidator
```

#### 4.2 Import Rules to instruction-history.json (1 hour)

**Automated import:**
```bash
node scripts/import-extracted-rules.js \
  /home/theflow/projects/family-history/CLAUDE_extracted_rules.json
```

**Manual additions:**
- 41 already-applicable Tractatus rules
- 13 framework-unlocked rules
- Any missing family-history-specific rules

**Validation:**
```bash
node scripts/analyze-instruction-database.js
# Verify ~61 total instructions
# Check for duplicates
# Validate quadrant/persistence distribution
```

**Time:** 2 hours
**Risk:** Low - documentation and data import

---

### Phase 5: Production Validation & Rollout (Careful Testing)

#### 5.1 Development Environment Testing (2 hours)

**Test on localhost:7000:**

1. **Session workflow:**
   - Start session with `node scripts/session-init.js`
   - Work on test feature (e.g., add contribution)
   - Verify framework monitoring (pressure checks)
   - End session with `node scripts/session-closedown.js`
   - Verify handoff document created

2. **Tenant isolation validation:**
   - Create query without tenantId filter
   - Verify CrossReferenceValidator catches it
   - Check audit log for violation record

3. **Boundary enforcement:**
   - Write comment with "guarantee 100% safe"
   - Verify BoundaryEnforcer blocks/warns
   - Check prohibited terms enforcement

4. **Framework triggers:**
   - Type "ff" to trigger full audit
   - Type "ffs" to view framework stats
   - Verify output includes all 6 services

#### 5.2 Production Safety Checks (1 hour)

**BEFORE deploying to production:**

1. **Framework is development-only**
   - Framework services run on developer machine
   - NOT deployed to production server
   - Production runtime doesn't need framework code

2. **Verify no production impact:**
   - Framework files in `.claude/` (not deployed)
   - Framework services in `src/services/` (not imported by production code)
   - Scripts in `scripts/` (not called by production)

3. **Safe framework installation:**
   - Framework exists in codebase for development
   - Production deployment scripts ignore `.claude/`
   - No runtime dependencies on framework

#### 5.3 Rollout Plan (Low Risk)

**Framework is development-time only:**
- ✅ Framework files live in codebase
- ✅ Used during development sessions
- ✅ NOT deployed to production
- ✅ NO production runtime impact

**Deployment:**
```bash
# Standard deployment (framework files not deployed)
./scripts/deploy-with-cache-bust.sh

# Production doesn't see:
# - .claude/* (excluded by rsync)
# - Framework services (not imported)
# - Session scripts (not called)
```

**Rollback:**
- If issues arise, simply don't use framework
- Framework is opt-in (run session-init.js to activate)
- Production code unchanged

**Time:** 3 hours
**Risk:** Low - framework is development-time only

---

## 📊 Success Criteria

### Framework Installation Success

- [ ] All 6 framework services initialize without errors
- [ ] Session-init.js completes successfully
- [ ] MongoDB connection works (port 27027)
- [ ] Audit logs created in database
- [ ] instruction-history.json contains ~61 rules
- [ ] Multi-tenant context detection works
- [ ] AsyncLocalStorage integration functional

### Multi-Tenant Adaptation Success

- [ ] Framework respects tenant boundaries
- [ ] Tenant context flows through all services
- [ ] Audit logs include activeTenantId
- [ ] No cross-tenant data leakage in framework
- [ ] Privacy logs remain separate from framework logs

### Governance Rule Coverage

- [ ] Layer 1 rules (4) imported and active
- [ ] Layer 2 rules (3) imported and active
- [ ] 41 already-applicable Tractatus rules adopted
- [ ] 13 framework-unlocked rules now operational
- [ ] Total: 61 active governance rules

### Development Workflow Integration

- [ ] Session startup smooth (session-init.js works)
- [ ] Token checkpoint reporting at 50k/100k/150k
- [ ] Framework triggers work ("ff", "ffs")
- [ ] Session closedown creates handoff documents
- [ ] Pre-action checks run before file edits (if hooks enabled)

### Production Safety

- [ ] Framework files not deployed to production
- [ ] Production runtime unaffected
- [ ] No performance impact on production
- [ ] Stroh tenant (beta) continues working normally

---

## ⚠️ Risk Mitigation

### Risk 1: Multi-Tenant Contamination

**Risk:** Framework state leaks across tenants

**Mitigation:**
- Framework is developer-scoped, not tenant-scoped
- Audit logs include activeTenantId but decisions are project-wide
- Test tenant isolation thoroughly in Phase 5.1
- Separate framework audit logs from tenant privacy logs

**Contingency:** If contamination detected, disable framework until fixed

---

### Risk 2: Performance Impact

**Risk:** Framework services slow down development

**Mitigation:**
- Framework only runs during development, not production
- Services are async and non-blocking
- Audit logging is fire-and-forget
- Monitor session-init.js startup time

**Contingency:** If too slow, make framework opt-in per session

---

### Risk 3: Database Schema Conflicts

**Risk:** AuditLog model conflicts with existing models

**Mitigation:**
- Use separate collection (`audit_logs` vs `privacyauditlogs`)
- Review schema before creation
- Test in development first
- No foreign key constraints that could break

**Contingency:** Rename collection if conflict arises

---

### Risk 4: Git/GitHub Migration Disruption

**Risk:** GitHub migration corrupts git history

**Mitigation:**
- Audit first, migrate later (Phase 2.2)
- Test migration on separate branch
- Backup entire repository before migration
- Document rollback procedure

**Contingency:** Defer migration if risk too high; framework works with local git

---

### Risk 5: Stroh Tenant (Production) Disruption

**Risk:** Framework installation breaks beta tenant

**Mitigation:**
- Framework is development-only (not deployed)
- Test extensively in localhost:7000 first
- Verify deploy scripts exclude `.claude/`
- Monitor production health after deployment

**Contingency:** Rollback deployment if issues; framework files not in production

---

## 📅 Timeline Estimate

| Phase | Duration | Dependencies |
|-------|----------|--------------|
| Phase 1: Preparation | 3 hours | None | ✅ **COMPLETE**
| Phase 2: Infrastructure | 3 hours | None (parallel to framework) |
| Phase 3: Framework Install | 8 hours | Phase 2 complete |
| Phase 4: CLAUDE.md & Import | 2 hours | Phase 3 complete |
| Phase 5: Validation & Rollout | 3 hours | Phase 4 complete |
| **Total** | **19 hours** | Linear progression |

**Recommended schedule:**
- Session 2 (Next): Phase 2 (Infrastructure) - 3 hours
- Session 3: Phase 3.1-3.4 (Framework copy & adapt) - 4 hours
- Session 4: Phase 3.5-3.7 (Instruction import & testing) - 4 hours
- Session 5: Phase 4 (CLAUDE.md & consolidation) - 2 hours
- Session 6: Phase 5 (Validation & rollout) - 3 hours

---

## 📝 Open Questions & Decisions Needed

### Decision 1: Git/GitHub Migration Timing

**Question:** Migrate to GitHub in Phase 2, or defer to later?

**Options:**
- A. Migrate in Phase 2 (before framework installation)
- B. Defer until framework stable
- C. Don't migrate (stay with local git + BorgBackup)

**Recommendation:** Audit in Phase 2, decide based on risk/benefit analysis

---

### Decision 2: Hook Validators

**Question:** Install Claude Code hook validators?

**Context:** family-history may use different IDE than Tractatus

**Options:**
- A. Install hooks if using Claude Code
- B. Skip hooks, rely on manual framework checks
- C. Create custom hooks for family-history workflow

**Recommendation:** Defer to Phase 3.7 testing; install if Claude Code is primary IDE

---

### Decision 3: Test Coverage Priority

**Question:** Add tests before or after framework installation?

**Context:** family-history has minimal test coverage (7 test files for 191k LOC)

**Options:**
- A. Add tests first (safety net before framework)
- B. Add tests during framework installation (test framework integration)
- C. Add tests after framework stable (incremental improvement)

**Recommendation:** Option B - test framework integration during Phase 3.7, then expand coverage incrementally

---

### Decision 4: Framework Service Customization

**Question:** Which framework services need family-history-specific logic?

**Candidates:**
- BoundaryEnforcer - Add GDPR prohibited terms?
- CrossReferenceValidator - Add tenant isolation checks?
- MetacognitiveVerifier - Add multi-tenant reasoning checks?

**Recommendation:** Start with Tractatus services as-is, customize based on Phase 5.1 testing feedback

---

## 🎯 Next Session Priorities

**Session 2 (Next):**

1. ✅ Move to `/home/theflow/projects/family-history` directory
2. ✅ SSL certificate renewal (if expiring)
3. ✅ Git/GitHub audit (decision on migration)
4. ✅ Backup system verification
5. ✅ Begin Phase 3.1 (create `.claude/` structure)

**Deliverables:**
- Infrastructure audit reports
- SSL certificate renewed (if needed)
- Git migration decision documented
- `.claude/` directory structure ready for framework

---

## 📚 Reference Documents

**Tractatus (Source):**
- `/home/theflow/projects/tractatus/CLAUDE.md` - Quick reference
- `/home/theflow/projects/tractatus/.claude/instruction-history.json` - Rule database
- `/home/theflow/projects/tractatus/CLAUDE_Tractatus_Maintenance_Guide.md` - Full guide
- `/home/theflow/projects/tractatus/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md` - Future multi-project vision

**family-history (Target):**
- `/home/theflow/projects/family-history/CLAUDE.md` - Current quick reference
- `/home/theflow/projects/family-history/docs/CLAUDE_MAINTENANCE_GUIDE_2025_09_30.md` - Existing maintenance guide
- `/home/theflow/projects/family-history/docs/MULTI_TENANT_TECHNICAL_SPEC.md` - Architecture spec

**This Plan:**
- `/home/theflow/projects/tractatus/FAMILY_HISTORY_FRAMEWORK_INTEGRATION_PLAN.md` - This document
- `/home/theflow/projects/tractatus/TRACTATUS_RULES_APPLICABILITY_ANALYSIS.json` - Detailed rule analysis
- `/home/theflow/projects/family-history/CLAUDE_extracted_rules.json` - Extracted rules from CLAUDE.md

---

## ✅ Phase 1 Completion Checklist

- [x] CLAUDE.md extraction script created (`analyze-claude-md.js`)
- [x] Extraction script tested on family-history CLAUDE.md
- [x] 7 rules extracted (4 Layer 1 + 3 Layer 2)
- [x] Applicability analysis completed (54 applicable rules identified)
- [x] Multi-tenant adaptation requirements documented
- [x] Integration plan created (this document)
- [x] Next session priorities defined

**Status:** ✅ **Phase 1 COMPLETE - Ready for Phase 2**

---

**Plan Version:** 1.0
**Last Updated:** 2025-11-01
**Next Review:** After Phase 2 completion (infrastructure setup)