tractatus/docs/FRAMEWORK_RULES_AUDIT.md

Framework Rules Audit & Taxonomy

Multi-Project Governance Analysis

Date: November 2, 2025 Auditor: Claude Code (Sonnet 4.5) Scope: family-history, tractatus projects

---

📊 EXECUTIVE SUMMARY

Project Comparison

Project	Total Rules	Schema Version	Status
family-history	31 rules	v2.0 (Enhanced)	✅ PRODUCTION
tractatus	50 rules	v1.0 (Original)	✅ PRODUCTION
TOTAL UNIQUE	~65 rules	Mixed	Harmonization needed

Key Findings

1. Schema Inconsistency: Two different rule schemas in use
2. Coverage Gaps: family-history missing 20+ rules present in tractatus
3. Duplication: ~15 rules exist in both projects with different IDs
4. Completeness: Neither project has COMPLETE coverage

---

🔍 DETAILED ANALYSIS

Schema Comparison

Family-History Schema (v2.0 - Enhanced)

{
  "id": "inst_fh_*_###",
  "title": "Human-readable title",
  "category": "SECURITY|MULTI_TENANCY|DEPLOYMENT|SYSTEM|VALUES_ALIGNMENT|PRIVACY",
  "quadrant": "STRATEGIC|OPERATIONAL",
  "persistence": "HIGH|MEDIUM|LOW",
  "description": "What this rule governs",
  "context": "Why this rule exists",
  "rationale": "Detailed reasoning",
  "trigger": "When to apply this rule",
  "action": "Specific steps to take",
  "validation": "How to verify compliance",
  "evidence": "Supporting documentation",
  "relatedInstructions": ["inst_*"],
  "metadata": {
    "created": "date",
    "lastValidated": "date",
    "violationCount": 0,
    "deactivated": false
  }
}

Strengths:

• Comprehensive documentation
• Clear action guidance
• Validation criteria
• Evidence tracking
• Relationship mapping

Weaknesses:

• More verbose
• Takes longer to create
• No temporal scope

---

Tractatus Schema (v1.0 - Original)

{
  "id": "inst_###",
  "text": "Complete instruction in one field",
  "timestamp": "ISO timestamp",
  "quadrant": "STRATEGIC|OPERATIONAL|TACTICAL|SYSTEM",
  "persistence": "HIGH|MEDIUM|LOW",
  "temporal_scope": "PROJECT|SESSION|TASK",
  "verification_required": "MANDATORY|RECOMMENDED|OPTIONAL",
  "explicitness": 0.0-1.0,
  "source": "user|system|framework",
  "session_id": "session identifier",
  "parameters": {},
  "active": true/false,
  "notes": "Additional context"
}

Strengths:

• Temporal scope tracking
• Verification requirements
• Explicitness scoring
• Source tracking
• Session binding

Weaknesses:

• Less structured documentation
• No separate action/validation
• No evidence tracking
• No relationship mapping

---

📋 RULE TAXONOMY BY CATEGORY

1. SECURITY Rules

Family-History Coverage (8 rules):

• ✅ inst_fh_sec_001: TenantStorage requirement (no localStorage)
• ✅ inst_fh_sec_002: Database connection script approval
• ✅ inst_fh_sec_003: Credential protection (never commit)
• ✅ inst_fh_sec_004: Server-provided context over client storage
• ✅ inst_fh_sec_005: XSS prevention through storage isolation
• ✅ inst_fh_sec_006: Backup credential protection
• ✅ inst_fh_sec_007: Session handoff check before work
• ✅ inst_fh_sec_008: CSP nonce-based policy protection

Tractatus Coverage (11 rules):

• ✅ inst_008_CONSOLIDATED: CSP compliance (HTML/JS)
• ✅ inst_012: No internal/confidential docs in production
• ✅ inst_013: No sensitive runtime data in public APIs
• ✅ inst_014: No API endpoint listings publicly
• ✅ inst_015: No internal dev docs in public downloads
• ✅ inst_041_CONSOLIDATED: File upload validation
• ✅ inst_043: User input sanitization
• ✅ inst_045: API rate limiting and protection
• ✅ inst_046: Security event logging
• ✅ inst_069: Credential redaction in documentation
• ✅ inst_070: Git commit secret detection

GAPS IN FAMILY-HISTORY:

• ❌ Public documentation security (inst_012, inst_015)
• ❌ API security details (inst_013, inst_014)
• ❌ File upload validation (inst_041)
• ❌ User input sanitization (inst_043)
• ❌ API rate limiting (inst_045)
• ❌ Security event logging (inst_046)
• ❌ Credential redaction (inst_069)
• ❌ Secret detection (inst_070)

---

2. MULTI-TENANCY Rules

Family-History Coverage (5 rules):

• ✅ inst_fh_multi_001: TenantId filtering mandatory
• ✅ inst_fh_multi_002: No hardcoded tenant IDs
• ✅ inst_fh_multi_003: Email isolation by tenant
• ✅ inst_fh_multi_004: Lowercase collection names
• ✅ inst_fh_multi_005: Tenant isolation verification

Tractatus Coverage:

• ✅ inst_058: Data sync field mapping (related)
• ⚠️ No explicit multi-tenancy rules (single-tenant project)

GAPS: None (family-history has complete coverage)

---

3. DEPLOYMENT Rules

Family-History Coverage (6 rules):

• ✅ inst_fh_deploy_001: Local testing mandatory
• ✅ inst_fh_deploy_002: Use cache-bust script
• ✅ inst_fh_deploy_003: No temporary bypasses
• ✅ inst_fh_deploy_004: Health check before deployment
• ✅ inst_fh_deploy_005: Browser F12 console testing
• ✅ inst_fh_deploy_006: Fix root causes not symptoms

Tractatus Coverage (7 rules):

• ✅ inst_020_CONSOLIDATED: File permissions on deployment
• ✅ inst_025: Rsync directory structure preservation
• ✅ inst_027: Sync instruction-history to production
• ✅ inst_056: Batch operation pattern validation
• ✅ inst_057: Rollback plan for critical changes
• ✅ inst_068: Test before commits/deployments
• ✅ inst_071: Pre-deployment checklist

GAPS IN FAMILY-HISTORY:

• ❌ File permission automation (inst_020)
• ❌ Directory structure preservation (inst_025)
• ❌ Instruction-history sync (inst_027)
• ❌ Rollback planning (inst_057)
• ❌ Testing requirements (inst_068)

---

4. SYSTEM/INFRASTRUCTURE Rules

Family-History Coverage (5 rules):

• ✅ inst_fh_sys_001: Systemd only (no PM2)
• ✅ inst_fh_sys_002: Correct database name (family_history)
• ✅ inst_fh_sys_003: Correct MongoDB port (27027)
• ✅ inst_fh_sys_004: Database isolation verification
• ✅ inst_fh_sys_005: Service name verification

Tractatus Coverage (4 rules):

• ✅ inst_001: MongoDB port 27017
• ✅ inst_002: Application port 9000
• ✅ inst_026: CLAUDE_API_KEY environment variable
• ✅ inst_067: Environment/port verification

GAPS IN FAMILY-HISTORY:

• ❌ AI API key configuration (inst_026)
• ❌ Environment verification pattern (inst_067)

---

5. FRAMEWORK OPERATION Rules

Family-History Coverage:

• ⚠️ Implicit in hook system, not explicit rules

Tractatus Coverage (7 rules):

• ✅ inst_006: ContextPressureMonitor session management
• ✅ inst_019: Context window consumption tracking
• ✅ inst_038: Pre-action-check before Edit/Write
• ✅ inst_064: Active framework component usage
• ✅ inst_065: Session initialization mandatory
• ✅ inst_027: Never modify instruction-history without approval
• ✅ inst_040: Handle "all" requests comprehensively

GAPS IN FAMILY-HISTORY:

• ❌ ContextPressureMonitor rules (inst_006, inst_019)
• ❌ Pre-action checks (inst_038)
• ❌ Framework usage requirements (inst_064, inst_065)
• ❌ Instruction modification rules (inst_027)
• ❌ "All" request handling (inst_040)

---

6. VALUES/GOVERNANCE Rules

Family-History Coverage (4 rules):

• ✅ inst_fh_values_001: Privacy sovereignty principle
• ✅ inst_fh_values_002: Anti-big-tech stance
• ✅ inst_fh_values_003: Family data autonomy
• ✅ inst_fh_values_004: Not genealogy - private communications

Tractatus Coverage (10 rules):

• ✅ inst_003: Project isolation
• ✅ inst_004: No shortcuts, world-class quality
• ✅ inst_005: Human approval for major decisions
• ✅ inst_016: No fabricated statistics
• ✅ inst_017: No absolute assurance terms
• ✅ inst_018: Honest readiness claims
• ✅ inst_047: Never dismiss user requests
• ✅ inst_049: Test user hypothesis first
• ✅ inst_052: Document scope adjustments
• ✅ inst_053: Document architectural decisions
• ✅ inst_055: Preserve working patterns
• ✅ inst_063_CONSOLIDATED: Public repo content restrictions

GAPS IN FAMILY-HISTORY:

• ❌ Quality standards (inst_004)
• ❌ Statistical accuracy (inst_016)
• ❌ Language accuracy (inst_017, inst_018)
• ❌ User request handling (inst_047, inst_049)
• ❌ Architectural documentation (inst_052, inst_053, inst_055)
• ❌ Public content restrictions (inst_063)

---

7. PRIVACY Rules

Family-History Coverage (3 rules):

• ✅ inst_fh_privacy_001: No analytics without approval
• ✅ inst_fh_privacy_002: User data protection
• ✅ inst_fh_privacy_003: Tenant isolation as privacy

Tractatus Coverage:

• ⚠️ Covered under security rules (no separate privacy category)

GAPS: None (family-history has privacy-specific rules)

---

8. GIT/VERSION CONTROL Rules

Family-History Coverage:

• ⚠️ Covered in deployment rules

Tractatus Coverage (3 rules):

• ✅ inst_061: Hook approval persistence
• ✅ inst_066: Conventional commit format
• ✅ inst_070: Secret detection in commits

GAPS IN FAMILY-HISTORY:

• ❌ Hook approval persistence (inst_061)
• ❌ Conventional commit format (inst_066)
• ❌ Secret detection (inst_070)

---

9. OPERATIONAL EXCELLENCE Rules

Tractatus-Only Coverage (6 rules):

• ✅ inst_009: Service status documentation
• ✅ inst_023: Background process management
• ✅ inst_039: Content update audit requirements
• ✅ inst_056: Batch operation validation
• ✅ inst_057: Rollback planning
• ✅ inst_068: Testing requirements

GAPS IN FAMILY-HISTORY:

• ❌ Background process management (inst_023)
• ❌ Content audit (inst_039)
• ❌ All operational excellence rules

---

🎯 RECOMMENDED ADDITIONS TO FAMILY-HISTORY

HIGH PRIORITY (Add Immediately)

1. inst_fh_sec_009: File Upload Validation

   • Based on tractatus inst_041_CONSOLIDATED
   • CRITICAL for multi-tenant security

2. inst_fh_sec_010: User Input Sanitization

   • Based on tractatus inst_043
   • CRITICAL for XSS/injection prevention

3. inst_fh_sec_011: API Rate Limiting

   • Based on tractatus inst_045
   • CRITICAL for DoS prevention

4. inst_fh_sec_012: Security Event Logging

   • Based on tractatus inst_046
   • CRITICAL for incident response

5. inst_fh_sec_013: Secret Detection in Commits

   • Based on tractatus inst_070
   • CRITICAL for credential protection

6. inst_fh_framework_001: Pre-Action Validation

   • Based on tractatus inst_038
   • CRITICAL for hook system integrity

7. inst_fh_framework_002: Never Modify instruction-history

   • Based on tractatus inst_027
   • CRITICAL for governance integrity

8. inst_fh_framework_003: Session Initialization Mandatory

   • Based on tractatus inst_065
   • CRITICAL for framework operation

9. inst_fh_framework_004: ContextPressureMonitor Usage

   • Based on tractatus inst_006, inst_019
   • CRITICAL for session management

10. inst_fh_git_001: Conventional Commit Format

    • Based on tractatus inst_066
    • HIGH importance for maintainability

---

MEDIUM PRIORITY (Add This Week)

11. inst_fh_deploy_007: File Permission Automation

    • Based on tractatus inst_020_CONSOLIDATED

12. inst_fh_deploy_008: Rollback Planning

    • Based on tractatus inst_057

13. inst_fh_deploy_009: Testing Requirements

    • Based on tractatus inst_068

14. inst_fh_quality_001: No Fabricated Statistics

    • Based on tractatus inst_016

15. inst_fh_quality_002: No Absolute Assurance Language

    • Based on tractatus inst_017

16. inst_fh_quality_003: Honest Readiness Claims

    • Based on tractatus inst_018

17. inst_fh_ops_001: Background Process Management

    • Based on tractatus inst_023

18. inst_fh_ops_002: Handle "All" Requests Comprehensively

    • Based on tractatus inst_040

19. inst_fh_ops_003: Test User Hypothesis First

    • Based on tractatus inst_049

20. inst_fh_arch_001: Document Architectural Decisions

    • Based on tractatus inst_053

---

LOW PRIORITY (Future Enhancement)

21-25. Content management rules (inst_039, inst_063, etc.) 26-30. Operational excellence patterns (inst_052, inst_055, inst_056)

---

🔧 SCHEMA HARMONIZATION PROPOSAL

Option 1: Dual Schema Support (Recommended)

• Keep both schemas
• Create conversion utilities
• Use enhanced schema for new rules
• Migrate tractatus gradually

Option 2: Full Migration to Enhanced Schema

• Convert all tractatus rules to v2.0 schema
• Significant effort (~20 hours)
• Better long-term consistency

Option 3: Create Unified v3.0 Schema

• Best of both schemas
• id, title, category, quadrant, persistence
• temporal_scope, verification_required (from tractatus)
• description, context, rationale, trigger, action, validation, evidence (from family-history)
• relatedInstructions, metadata

---

✅ COMPLETENESS ASSESSMENT

Family-History Project

Category	Coverage	Status
Security	8/19 rules	⚠️ 42% - GAPS EXIST
Multi-Tenancy	5/5 rules	✅ 100% - COMPLETE
Deployment	6/13 rules	⚠️ 46% - GAPS EXIST
System	5/9 rules	⚠️ 56% - GAPS EXIST
Framework Operation	0/7 rules	❌ 0% - CRITICAL GAPS
Values/Governance	4/14 rules	⚠️ 29% - GAPS EXIST
Privacy	3/3 rules	✅ 100% - COMPLETE
Git/Version Control	0/3 rules	❌ 0% - GAPS EXIST
Operational Excellence	0/6 rules	❌ 0% - GAPS EXIST

OVERALL: 31/65 rules (48% coverage)

Critical Gaps:

1. ❌ Framework Operation - 0% coverage (CRITICAL)
2. ❌ Git/Version Control - 0% coverage
3. ❌ Operational Excellence - 0% coverage
4. ⚠️ Security - Missing API security, input validation, rate limiting
5. ⚠️ Deployment - Missing testing, rollback, permissions
6. ⚠️ Values/Governance - Missing quality standards, documentation requirements

---

🚨 IMMEDIATE ACTION REQUIRED

Step 1: Add Critical Security Rules (TODAY)

# Add to family-history/.claude/instruction-history.json:
- inst_fh_sec_009: File upload validation
- inst_fh_sec_010: User input sanitization
- inst_fh_sec_011: API rate limiting
- inst_fh_sec_012: Security event logging
- inst_fh_sec_013: Secret detection

Step 2: Add Framework Operation Rules (TODAY)

# Add to family-history/.claude/instruction-history.json:
- inst_fh_framework_001: Pre-action validation
- inst_fh_framework_002: Never modify instruction-history
- inst_fh_framework_003: Session initialization
- inst_fh_framework_004: ContextPressureMonitor usage

Step 3: Add Git Rules (THIS WEEK)

# Add to family-history/.claude/instruction-history.json:
- inst_fh_git_001: Conventional commits
- inst_fh_git_002: Secret detection

Step 4: Add Deployment Rules (THIS WEEK)

# Add to family-history/.claude/instruction-history.json:
- inst_fh_deploy_007: File permissions
- inst_fh_deploy_008: Rollback planning
- inst_fh_deploy_009: Testing requirements

---

📊 RULE DISTRIBUTION ANALYSIS

By Quadrant

Quadrant	Family-History	Tractatus	Total
STRATEGIC	15 (48%)	20 (40%)	35
OPERATIONAL	12 (39%)	22 (44%)	34
TACTICAL	0 (0%)	2 (4%)	2
SYSTEM	4 (13%)	6 (12%)	10

By Persistence

Persistence	Family-History	Tractatus	Total
HIGH	28 (90%)	47 (94%)	75
MEDIUM	3 (10%)	3 (6%)	6
LOW	0 (0%)	0 (0%)	0

Observation: Almost all rules are HIGH persistence - indicates critical governance requirements.

---

🎯 SUCCESS CRITERIA

Family-history rules considered COMPLETE when:

• Security coverage: ≥90% (need 17/19 rules)
• Framework operation: 100% (need 7/7 rules)
• Git/version control: 100% (need 3/3 rules)
• Deployment: ≥75% (need 10/13 rules)
• Operational excellence: ≥50% (need 3/6 rules)
• Overall coverage: ≥75% (need 49/65 rules)

Current Progress: 31/65 (48%) → Need 18+ more rules

---

📝 NEXT STEPS

1. User Approval: Review this audit and approve recommended additions
2. Priority 1: Add 10 HIGH PRIORITY rules (security + framework)
3. Priority 2: Add 10 MEDIUM PRIORITY rules (deployment + quality)
4. Priority 3: Consider schema harmonization approach
5. Validation: Test new rules with governance hook
6. Documentation: Update GOVERNANCE_FRAMEWORK.md

---

Audit Completed: November 2, 2025 12:00 UTC Next Review: After rule additions, or December 2, 2025 Auditor: Claude Code (Sonnet 4.5) Confidence: HIGH (based on complete file reads)

---

📄 LICENSE & COPYRIGHT

License: Apache License 2.0 Copyright: © 2025 John G Stroh. All rights reserved.

This audit is part of the Family History Portal project.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.