tractatus/docs/FRAMEWORK_RULES_AUDIT.md
TheFlow 2a727a80b8 feat: Complete Phase 2 Agent Lightning website integration
- Added Agent Lightning research section to researcher.html with Demo 2 results
- Created comprehensive /integrations/agent-lightning.html page
- Added Agent Lightning link in homepage hero section
- Updated Discord invite links (Tractatus + semantipy) across all pages
- Added feedback.js script to all key pages for live demonstration

Phase 2 of Master Plan complete: Discord setup → Website completion

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-03 14:38:20 +13:00

562 lines
17 KiB
Markdown

# 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)
```json
{
"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)
```json
{
"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)
```bash
# 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)
```bash
# 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)
```bash
# 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)
```bash
# 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.