john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor(public): remove 6 internal project files from public repository

Browse source 
Removed files:
- SECURITY_INCIDENT_HUMAN_ACTIONS_REQUIRED.md (internal security doc)
- .claude/instruction-history.json (project-specific governance rules)
- scripts/add-security-rules-2025-10-21.js (dated, project-specific)
- scripts/apply-governance-audit-2025-10-21.js (dated, project-specific)
- docs/governance/GOVERNANCE_LEARNINGS_2025-10-21.md (internal learnings)
- docs/governance/GOVERNANCE_RULES_AUDIT_2025-10-21.md (internal audit)

These are internal to the tractatus project, not framework resources.
Public repo should contain only framework implementation code and docs.

Updated .gitignore to prevent future commits of similar files.
This commit is contained in:
TheFlow 2025-10-22 17:08:23 +13:00
parent 219a117799
commit 02e75949df
7 changed files with 8 additions and 5155 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2461
.claude/instruction-history.json
View file

File diff suppressed because it is too large Load diff

8
.gitignore vendored
View file

@ -211,3 +211,11 @@ scripts/test-deliberation*.js
public/downloads/*claude-code*.pdf
public/downloads/*governance-in-action*.pdf
SECURITY_INCIDENT_POST_MORTEM_2025-10-21.md
# Internal project-specific files (not framework)
SECURITY_INCIDENT_HUMAN_ACTIONS_REQUIRED.md
.claude/instruction-history.json
scripts/add-security-rules-*.js
scripts/apply-governance-audit-*.js
docs/governance/GOVERNANCE_LEARNINGS_*.md
docs/governance/GOVERNANCE_RULES_AUDIT_*.md

533
SECURITY_INCIDENT_HUMAN_ACTIONS_REQUIRED.md
View file

@ -1,533 +0,0 @@
# SECURITY INCIDENT - HUMAN ACTIONS REQUIRED
**Date**: 2025-10-21
**Incident**: Anthropic API Key Exposure + Additional Credentials Found
**Severity**: CRITICAL
**Status**: IMMEDIATE ACTION REQUIRED
---
## EXECUTIVE SUMMARY
**What Happened**:
1. Anthropic API key exposed in public GitHub repository (tractatus-framework)
2. Key automatically revoked by Anthropic (good - their secret scanning worked)
3. Comprehensive scan revealed ADDITIONAL exposed credentials in internal repository
**Credentials Found**:
1. ✅ Anthropic API key (REVOKED by Anthropic)
2. ❌ SAME Anthropic key STILL in `.env` file (internal repo)
3. ❌ SAME Anthropic key STILL in `docs/STRIPE_LIVE_MODE_DEPLOYMENT.md` (internal repo)
4. ❌ Stripe TEST keys in `.env` (low risk, but still credentials)
5. ❌ JWT secret in `.env` (production secret)
**Your Action**: Follow checklist below IMMEDIATELY
---
## CRITICAL - IMMEDIATE ACTIONS (Next 30 Minutes)
### 1. Rotate Anthropic API Key ✅ HIGHEST PRIORITY
**Why**: Same key that was exposed publicly is STILL in internal repository
**Actions**:
1. Login to Anthropic Console: https://platform.claude.com/settings/keys
2. Verify key `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` is revoked
- Key ID: 5043627
- Key Name: family-history-ocr
- Status should show: **REVOKED**
3. Create NEW API key:
- Name: `tractatus-production-2025-10-21` (or similar)
- Description: "Replaces compromised key family-history-ocr"
- Copy new key (starts with `sk-ant-api03-`)
4. Update `.env` file:
```bash
# Open .env file
nano /home/theflow/projects/tractatus/.env
# Replace OLD key with NEW key:
# OLD: CLAUDE_API_KEY=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
# NEW: CLAUDE_API_KEY=sk-ant-api03-YOUR_NEW_KEY_HERE
# Save and exit (Ctrl+X, Y, Enter)
```
5. Test new key:
```bash
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: sk-ant-api03-YOUR_NEW_KEY_HERE" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{"model": "claude-sonnet-4-5-20250929", "max_tokens": 10, "messages": [{"role": "user", "content": "test"}]}'
# Should return valid response (not 401 error)
```
**Verification**: New key works, old key definitely revoked
---
### 2. Remove Exposed Key from Documentation ✅ CRITICAL
**Why**: `docs/STRIPE_LIVE_MODE_DEPLOYMENT.md` contains the SAME exposed key
**Actions**:
```bash
# Edit the file
nano /home/theflow/projects/tractatus/docs/STRIPE_LIVE_MODE_DEPLOYMENT.md
# Find line with: CLAUDE_API_KEY=sk-ant-api03-_xmqWkax8jx...
# Replace with: CLAUDE_API_KEY=sk-ant-api03-EXAMPLE-REDACTED-NEVER-USE
# Save and exit
```
**Alternative** (automated):
```bash
sed -i 's/CLAUDE_API_KEY=sk-ant-api03-[a-zA-Z0-9_-]*/CLAUDE_API_KEY=sk-ant-api03-EXAMPLE-REDACTED-NEVER-USE/g' docs/STRIPE_LIVE_MODE_DEPLOYMENT.md
```
**Verification**: No real API keys in documentation
---
### 3. Rotate JWT Secret ✅ HIGH PRIORITY
**Why**: JWT secret in `.env` is production credential used for authentication
**Current Secret** (EXPOSED):
```
d4d9b5ac258123dbab38abf5ca7cd6274e2247d247a5a4fc18a031853cb332ec9d661f2cdb6aac7288bfffdcfb69b7c34cef84d342c139e69064941a8525f4c5
```
**Actions**:
1. Generate new JWT secret:
```bash
# Generate secure random secret (64 bytes hex)
openssl rand -hex 64
# Copy the output
```
2. Update `.env`:
```bash
nano .env
# Replace:
# OLD: JWT_SECRET=d4d9b5ac258123db...
# NEW: JWT_SECRET=<paste_new_secret_here>
# Save and exit
```
3. **IMPORTANT**: This will invalidate ALL existing JWT tokens
- All users will need to re-login
- Any admin sessions will be terminated
- This is CORRECT behavior (invalidates potentially compromised sessions)
**Verification**: Server starts successfully with new JWT secret
---
### 4. Rotate Stripe Keys (OPTIONAL - Low Risk) ⚠️ MEDIUM PRIORITY
**Why**: Stripe TEST keys found in `.env` (not live keys, low financial risk)
**Current Keys** (TEST mode):
- Secret: `sk_test_51RX67kGhfAwOYBrf2yU9XCbjkJERKuYhvreL5bFOV7Rr2qdDlHbVRobZ7bz7bC7ZR89q2aI4fX6rubqTl7iH2Y3U001FPAsNxr`
- Publishable: `pk_test_51RX67kGhfAwOYBrfbow71FlMSRR2fZlWysLV5w9oV0ylCFf5nLL4Aoin2SWBnmgnkBv6pusOlfxctt9kRBKHOjWC00XGag29RO`
**Risk Assessment**:
- These are TEST keys (sk_test_, pk_test_)
- No real money can be charged
- Still best practice to rotate
**Actions** (if you want to rotate):
1. Login to Stripe Dashboard: https://dashboard.stripe.com/test/apikeys
2. Roll secret key (this creates new key and invalidates old)
3. Copy new keys
4. Update `.env`:
```bash
STRIPE_SECRET_KEY=sk_test_YOUR_NEW_SECRET_KEY
STRIPE_PUBLISHABLE_KEY=pk_test_YOUR_NEW_PUBLISHABLE_KEY
```
**Decision**: Your call - test keys have low risk, but rotation is prudent
---
## SECONDARY ACTIONS (Next 1-2 Hours)
### 5. Install Gitleaks (Secret Detection Tool)
**Why**: Prevents future credential exposure with automated pre-commit scanning
**Installation** (Linux):
```bash
# Download gitleaks
wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.1/gitleaks_8.18.1_linux_x64.tar.gz
# Extract
tar -xzf gitleaks_8.18.1_linux_x64.tar.gz
# Move to /usr/local/bin
sudo mv gitleaks /usr/local/bin/
# Verify installation
gitleaks version
```
**Installation** (Mac - if applicable):
```bash
brew install gitleaks
```
**Test**:
```bash
# Scan repository
cd /home/theflow/projects/tractatus
gitleaks detect --source . --verbose
# Should detect credentials in .env, docs/STRIPE_LIVE_MODE_DEPLOYMENT.md
```
---
### 6. Create Git Pre-Commit Hook
**Why**: Blocks commits containing secrets BEFORE they reach git history
**Actions**:
```bash
# Navigate to repository
cd /home/theflow/projects/tractatus
# Create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
echo "🔍 Running secret detection scan..."
gitleaks detect --source . --verbose --no-git
if [ $? -ne 0 ]; then
echo ""
echo "❌ SECRETS DETECTED - Commit blocked"
echo ""
echo "If this is a false positive:"
echo " 1. Verify it's NOT a real secret"
echo " 2. Add to .gitleaksignore with explanation"
echo " 3. Get user approval"
echo " 4. Try committing again"
echo ""
exit 1
fi
echo "✅ No secrets detected - proceeding with commit"
exit 0
EOF
# Make executable
chmod +x .git/hooks/pre-commit
# Test
echo "test-secret=sk-ant-api03-test" > test-file.txt
git add test-file.txt
git commit -m "test" # Should BLOCK with secret detection error
rm test-file.txt
git reset HEAD test-file.txt
```
**Verification**: Committing a file with API key pattern is BLOCKED
---
### 7. Add .env to .gitignore (If Not Already)
**Why**: Ensures .env never accidentally committed
**Actions**:
```bash
# Check if .env in .gitignore
grep "^\.env$" .gitignore
# If not found, add it:
echo ".env" >> .gitignore
# Verify
cat .gitignore | grep "\.env"
```
**Verification**: .env appears in .gitignore
---
### 8. Remove docs/STRIPE_LIVE_MODE_DEPLOYMENT.md from Public Repository
**Why**: This file was exposed in public repo at commit 31345d5c1abc8c8da9387d55494a1741f451f9a7
**Decision Required**:
**Option A**: Delete file from git history (RECOMMENDED)
- Pros: Removes credential from git history
- Cons: Force push required, breaks forks
- Tool: BFG Repo-Cleaner
**Option B**: Accept file in history, rely on key revocation
- Pros: No repository disruption
- Cons: Credential remains in git history (already revoked)
- Action: None needed
**Option C**: Delete public repository and recreate
- Pros: Complete removal
- Cons: Loses stars, discussions, community engagement
**Recommendation**: Option B (accept in history) since:
1. Key already revoked by Anthropic
2. Public repo is tractatus-framework (implementation only)
3. No active community yet (early stage)
4. Low risk of exploitation (key revoked)
**If you choose Option A** (remove from history):
```bash
# Install BFG Repo-Cleaner
wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
java -jar bfg-1.14.0.jar --delete-files STRIPE_LIVE_MODE_DEPLOYMENT.md /path/to/tractatus-framework
# Follow BFG instructions to git reflog expire and force push
```
**Your Decision**: Which option?
---
### 9. Review All .env Files Across All Projects
**Why**: If one project exposed credentials, others might too
**Projects to Check**:
1. `/home/theflow/projects/tractatus` (DONE - issues found)
2. `/home/theflow/projects/family-history` (CHECK THIS)
3. `/home/theflow/projects/sydigital` (CHECK THIS)
4. Any other projects
**Actions for Each Project**:
```bash
# Navigate to project
cd /home/theflow/projects/PROJECTNAME
# Check .env exists
ls -la .env
# Scan for credentials
gitleaks detect --source . --verbose
# Check if .env in git history (BAD if true)
git log --all --full-history -- .env
```
**Verification**: No .env files in git history across any project
---
## MONITORING & VERIFICATION (Next 24-48 Hours)
### 10. Monitor Anthropic API Usage
**Why**: Detect unauthorized usage of compromised key (before revocation)
**Actions**:
1. Login to Anthropic Console: https://platform.claude.com/settings/usage
2. Review API usage for past 24 hours
3. Look for:
- Unusual volume spikes
- Geographic anomalies (API calls from unexpected regions)
- Unknown application names
- Timestamp gaps (usage when you weren't working)
**Red Flags**:
- API calls from non-Europe/non-Australia IPs (if you're only in those regions)
- Calls during hours you weren't working (e.g., 2-6 AM your timezone)
- Sudden spike in usage
- Unfamiliar model names or endpoints
**Action if Suspicious**: Contact Anthropic support immediately
---
### 11. Monitor Stripe Dashboard
**Why**: Detect unauthorized test transactions (low risk with test keys)
**Actions**:
1. Login to Stripe Dashboard: https://dashboard.stripe.com/test/payments
2. Review test transactions for past 7 days
3. Look for unexpected test charges
**Note**: Test keys cannot charge real money, so financial risk is zero
---
### 12. Review Git Log for Other Credential Exposures
**Why**: May have committed other secrets in past
**Actions**:
```bash
cd /home/theflow/projects/tractatus
# Scan entire git history for secrets
gitleaks detect --source . --log-opts="--all" --verbose --report-path=/tmp/gitleaks-report.json
# Review report
cat /tmp/gitleaks-report.json | jq '.'
# Or use grep for common patterns
git log -p --all | grep -E "sk-|pk-|api.?key|secret|password" | head -50
```
**Action if Found**: Rotate those credentials too
---
## POST-INCIDENT IMPROVEMENTS
### 13. Update SECURITY.md in Public Repository
**Why**: Transparency and incident disclosure
**Actions**:
1. Add incident to Security Audit History table
2. Document response (key revocation, rotation procedures)
3. Update best practices based on learnings
**Draft Entry**:
```markdown
| Date | Type | Severity | Status | Details |
|------|------|----------|--------|---------|
| 2025-10-21 | Credential Exposure | CRITICAL | Resolved | Anthropic API key exposed in docs/STRIPE_LIVE_MODE_DEPLOYMENT.md at commit 31345d5c1a. Key automatically revoked by Anthropic via GitHub secret scanning. All credentials rotated. Pre-commit secret detection implemented. |
```
---
### 14. Document Incident in Internal Post-Mortem
**File**: `docs/security/INCIDENT_2025-10-21_API_KEY_EXPOSURE.md`
**Sections**:
1. Timeline
2. Root cause
3. Impact assessment
4. Response actions
5. Preventive measures
6. Lessons learned
**Claude will create this** - see SECURITY_INCIDENT_POST_MORTEM_2025-10-21.md
---
### 15. Review and Test Pre-Deployment Checklist
**Why**: Ensure inst_071 (new enhanced checklist) prevents recurrence
**Actions**:
1. Review inst_071 checklist
2. Practice running each step
3. Identify any gaps
4. Update checklist if needed
**Checklist** (from inst_071):
```
□ 1. CSP Compliance Check [AUTOMATED via hook]
□ 2. Secret Detection Scan (gitleaks detect --source .)
□ 3. Credential Audit (grep -r "sk-" "pk-" "secret" "password")
□ 4. Local Server Test (curl http://localhost:9000/health → 200 OK)
□ 5. Comprehensive Testing (npm test → all pass)
□ 6. Permission Verification (ls -la → correct 644/755)
□ 7. Git Status Clean (no uncommitted changes)
□ 8. Public Repository Content Review (no internal docs)
```
---
## SUMMARY CHECKLIST
Use this to track completion:
**CRITICAL (Do Now)**:
- [ ] Rotate Anthropic API key (create new, update .env)
- [ ] Remove exposed key from docs/STRIPE_LIVE_MODE_DEPLOYMENT.md
- [ ] Rotate JWT secret (generate new, update .env)
- [ ] Test application with new credentials
**HIGH PRIORITY (Next 2 Hours)**:
- [ ] Install gitleaks
- [ ] Create pre-commit hook
- [ ] Verify .env in .gitignore
- [ ] Decide on public repo history (Option A/B/C)
**MEDIUM PRIORITY (Next 24 Hours)**:
- [ ] Rotate Stripe test keys (optional)
- [ ] Review other projects (.env files)
- [ ] Monitor Anthropic API usage
- [ ] Monitor Stripe dashboard
- [ ] Scan git history for other secrets
**LOW PRIORITY (Next Week)**:
- [ ] Update SECURITY.md
- [ ] Review post-mortem
- [ ] Test pre-deployment checklist
- [ ] Schedule quarterly security audits
---
## QUESTIONS & CLARIFICATIONS
### Q: Why did this happen?
**A**: Multiple failures in credential handling:
1. Real API key in documentation (should have been redacted example)
2. No secret detection before commit (no pre-commit hook)
3. No credential audit in cleanup checklist (inst_054 didn't include secret scan)
4. Framework components not actively used (BoundaryEnforcer should have caught this)
### Q: Was this malicious AI behavior?
**A**: NO. This was systematic failure in processes, not AI having "bad intent":
- AI doesn't have intent (good or bad)
- AI made mistakes that had catastrophic consequences
- Framework existed but wasn't enforced (framework fade)
- New rules (inst_069-072) prevent recurrence
### Q: What's the financial impact?
**A**: MINIMAL (likely zero):
- Anthropic key revoked immediately (GitHub secret scanning worked)
- No evidence of unauthorized usage (monitor to confirm)
- Stripe keys are TEST mode only (no real money)
- JWT secret rotation invalidates sessions (security benefit)
### Q: Will this happen again?
**A**: NOT if we follow new procedures:
- inst_069: Mandatory credential redaction
- inst_070: Pre-commit secret detection (automated)
- inst_071: Enhanced deployment checklist (includes credential audit)
- inst_072: Defense-in-depth (5 layers of protection)
- Gitleaks hook: Blocks commits with secrets
### Q: Should I be worried about other credentials?
**A**: YES - Audit recommended:
- Review all projects for .env files
- Scan git history with gitleaks
- Rotate credentials found in scans
- Implement secret detection across all projects
---
## CONTACT & SUPPORT
**Anthropic Support**: https://support.anthropic.com
**Stripe Support**: https://support.stripe.com
**GitHub Security**: https://docs.github.com/en/code-security/secret-scanning
**Internal**: Review SECURITY_INCIDENT_POST_MORTEM_2025-10-21.md for full analysis
---
**CREATED**: 2025-10-21 by Claude Code (Automated Security Response)
**URGENCY**: IMMEDIATE ACTION REQUIRED
**NEXT REVIEW**: After completing CRITICAL section (next 30 minutes)

596
docs/governance/GOVERNANCE_LEARNINGS_2025-10-21.md
View file

@ -1,596 +0,0 @@
# Governance Learnings - Session 2025-10-21
**Date**: 2025-10-21
**Session**: 2025-10-07-001 (continued)
**Context**: Comprehensive governance rules audit and optimization
---
## Executive Summary
This session conducted a comprehensive audit of the Tractatus governance framework, identifying and fixing critical enforcement gaps while optimizing rule structure for clarity and effectiveness.
**Key Achievement**: Transformed governance framework from 54 rules with significant overlaps and gaps into 56 highly-optimized rules with complete coverage and zero redundancy.
---
## What We Did
### 1. Comprehensive Audit (86,000 tokens of analysis)
**Scope**: Audited all 54 active governance rules against:
- CLAUDE.md requirements
- CLAUDE_Tractatus_Maintenance_Guide.md specifications
- Appropriateness, completeness, specificity criteria
- Overlap and conflict detection
**Methodology**:
- Read instruction-history.json (all 54 rules)
- Cross-referenced with project documentation
- Analyzed distribution (quadrant, persistence, scope)
- Evaluated actionability and enforceability
- Identified coverage gaps and redundancies
**Output**: 25-page comprehensive audit report with specific recommendations
### 2. Implementation (Applied all recommendations)
**Changes Made**:
1. **Consolidated 12 overlapping rules → 4 comprehensive rules** (-8 rules)
2. **Created 5 new rules to fill coverage gaps** (+5 rules)
3. **Split 1 overly broad rule into 5 granular rules** (+4 rules)
4. **Enhanced 3 vague rules with specific guidance** (clarity improvements)
5. **Adjusted 4 rules' persistence/quadrant classifications** (better organization)
6. **Updated 1 rule's text to reflect current state** (accuracy)
**Net Result**: 54 → 56 rules (+2 rules, +40% quality improvement)
### 3. Database Synchronization
**Created**: Sync script to maintain consistency between file and database
- `scripts/sync-instructions-to-db.js`
- Handles inserts, updates, deactivations
- Validates counts match between JSON and MongoDB
- Preserves audit trail (deprecation reasons, adjustment history)
**Verified**: MongoDB governanceRules collection synced (56 active rules)
### 4. Documentation
**Created**:
- `GOVERNANCE_RULES_AUDIT_2025-10-21.md` (comprehensive audit report)
- `GOVERNANCE_LEARNINGS_2025-10-21.md` (this document)
- `scripts/apply-governance-audit-2025-10-21.js` (migration script)
- `scripts/sync-instructions-to-db.js` (ongoing sync tool)
---
## Critical Findings
### Finding 1: Framework Component Usage NOT Enforced
**Problem**: CLAUDE_Maintenance_Guide documents 6 mandatory framework components, but inst_007 just said "use framework actively" (too vague for enforcement)
**Components Missing Coverage**:
1. ContextPressureMonitor
2. InstructionPersistenceClassifier
3. CrossReferenceValidator
4. BoundaryEnforcer
5. MetacognitiveVerifier
6. PluralisticDeliberationOrchestrator
**Impact**: Framework fade (components not being used) is documented as CRITICAL FAILURE, but no rule specified when to use each component
**Solution**: Created inst_064 with explicit triggers:
- ContextPressureMonitor: Session start, 50k/100k/150k tokens, after complex ops, after errors
- InstructionPersistenceClassifier: When user gives explicit instruction
- CrossReferenceValidator: Before DB/config/architecture changes
- BoundaryEnforcer: Before values/privacy/ethical decisions
- MetacognitiveVerifier: Operations with 3+ files or 5+ steps
- PluralisticDeliberationOrchestrator: When values conflict detected
**Result**: Framework usage now enforceable, not just aspirational
---
### Finding 2: Session Initialization NOT Enforced
**Problem**: CLAUDE.md requires `node scripts/session-init.js` IMMEDIATELY at session start and after compaction, but no rule enforced this
**Impact**: Sessions could start without framework operational, leading to degraded behavior
**Solution**: Created inst_065 with mandatory initialization protocol:
1. Run session-init.js
2. Report server status (curl health endpoint)
3. Report framework stats (session ID, active instructions, version)
4. Report MongoDB status (active rules count)
5. BLOCK all work until initialization complete and reported
**Result**: Every session now starts with verified framework operational state
---
### Finding 3: Environment Verification Prevents 27027 Failures
**Problem**: 27027 incident (pattern recognition bias) not prevented by any rule
**27027 Failure Mode**:
- User says: "Check port 27027"
- Claude does: Uses port 27017 (standard default)
- Root cause: Training data's "MongoDB = 27017" association overrides explicit instruction
**Impact**: Pattern recognition can override explicit user instructions without Claude even "hearing" the instruction
**Solution**: Created inst_067 with explicit verification protocol:
1. VERIFY current environment (local vs production)
2. VERIFY correct port/database from user instruction OR CLAUDE.md defaults
3. If user specifies non-standard value, USE EXACT VALUE - do NOT autocorrect to standards
4. When in doubt, ask user to confirm
**Result**: Protection against pattern recognition bias overriding explicit instructions
---
### Finding 4: Security Rules Had 7 Redundancies
**Problem**: CSP compliance covered by 3 separate rules (inst_008, inst_044, inst_048) with partial overlap
**Other Overlaps**:
- Deployment permissions: inst_020, inst_022 (both about file permissions)
- File upload validation: inst_041, inst_042 (uploads vs email attachments)
- Public GitHub management: inst_028, inst_062, inst_063 (partial overlap)
**Impact**: Cognitive load, potential conflicts, unclear which rule to follow
**Solution**: Consolidated into 4 comprehensive rules:
- inst_008_CONSOLIDATED: All CSP and security headers in one place
- inst_020_CONSOLIDATED: All deployment permission requirements unified
- inst_041_CONSOLIDATED: All file input validation (uploads, attachments, user files)
- inst_063_CONSOLIDATED: Complete public GitHub policy with weekly review requirement
**Result**: Single source of truth for each security domain, -7 overlapping rules
---
### Finding 5: Session Closedown Too Broad
**Problem**: inst_024 covered 5 separate closedown steps in one rule, making granular enforcement difficult
**Steps Conflated**:
1. Background process cleanup
2. Database sync verification
3. Git state documentation
4. Temporary artifact cleanup
5. Handoff document creation
**Impact**: Difficult to verify each step independently, easy to skip steps
**Solution**: Split into inst_024a/b/c/d/e with:
- Each step as separate rule
- Clear verification criteria
- Numbered sequence (step 1, step 2, etc.)
- Part of "inst_024_series" for grouping
**Result**: Granular enforcement, checkboxes for each closedown step
---
### Finding 6: Git Commit Conventions Not Enforced
**Problem**: CLAUDE_Maintenance_Guide documents conventional commit format, but no rule enforced it
**Current State**: Documented standard exists but compliance voluntary
**Solution**: Created inst_066 with mandatory format:
- Type(scope): description
- Types: feat, fix, docs, refactor, test, chore
- Claude Code attribution footer required
- NEVER use git commit -i (not supported)
- Verify authorship before amending commits
**Result**: Consistent git history, attribution transparency, prevents accidental amends
---
### Finding 7: Test Execution Requirements Missing
**Problem**: No rule specified when to run tests or how to handle failures
**Impact**: Unclear expectations for test-driven development, risk of deploying broken code
**Solution**: Created inst_068 with clear requirements:
- Before commits (if tests exist for modified area)
- Before deployments (full suite)
- After refactoring (affected tests)
- Test failures BLOCK commits/deployments (unless user approves)
- Ask user if tests should be written (don't assume)
- Report results: X passed, Y failed, Z skipped
**Result**: World-class quality standard (inst_004) now has enforcement mechanism
---
## Key Learnings
### 1. Documentation ≠ Enforcement
**Observation**: Many requirements were documented in CLAUDE_Maintenance_Guide but not present as enforceable rules
**Examples**:
- Framework component usage: Documented extensively, zero enforcement
- Session initialization: Required in CLAUDE.md, not enforced
- Git conventions: Specified in guide, voluntary compliance
**Lesson**: If something is critical, it must exist as a HIGH persistence rule, not just documentation
**Action**: Created inst_064, inst_065, inst_066 to fill enforcement gaps
### 2. Vague Rules Are Ineffective Rules
**Observation**: inst_007 said "use framework actively" but provided no specifics
**Problem**: Claude cannot enforce vague guidance
- What does "actively" mean?
- Which components, when?
- How to verify compliance?
**Lesson**: Effective rules specify:
1. **WHAT** to do (specific action)
2. **WHEN** to do it (clear triggers)
3. **HOW** to verify (measurable outcomes)
**Action**: Replaced inst_007 with inst_064 (explicit component usage triggers)
### 3. Overlap Creates Confusion
**Observation**: CSP compliance appeared in 3 rules with partial overlap
**Problem**: When faced with decision, which rule applies?
- inst_008: CSP in HTML/JS
- inst_044: Security headers including CSP
- inst_048: Hook validators must check CSP
**Lesson**: Consolidate related requirements into single comprehensive rule
**Action**: Created inst_008_CONSOLIDATED as single source of truth
### 4. Broad Rules Resist Granular Enforcement
**Observation**: inst_024 covered 5 closedown steps in one rule
**Problem**: Cannot mark "partially complete" - either done or not done
- Completed background cleanup but not git documentation
- Difficult to track progress through multi-step process
**Lesson**: Split complex procedures into granular checkboxes
**Action**: inst_024 → inst_024a/b/c/d/e (each step independently verifiable)
### 5. Pattern Recognition Bias Needs Explicit Protection
**Observation**: 27027 incident showed training data can override explicit instructions
**Insight**: As AI capabilities increase, training patterns get STRONGER (not weaker)
- More data = stronger associations
- MongoDB port 27017 appears millions of times in training data
- User saying "27027" gets auto-corrected by pattern recognition
**Lesson**: Rules must explicitly warn about pattern recognition bias and require verification
**Action**: Created inst_067 with "USE EXACT USER VALUE" emphasis and 27027 failure mode explanation
### 6. Persistence Levels Matter
**Observation**: 94% of rules marked HIGH persistence (51/54)
**Problem**: Everything marked critical = nothing is critical
- Signal-to-noise ratio issue
- Cognitive load from too many "critical" rules
**Lesson**: Reserve HIGH for truly permanent requirements, use MEDIUM for implementation details
**Action**: Lowered inst_011, inst_021 from HIGH → MEDIUM (appropriate for their scope)
### 7. Quadrant Classification Impacts Organization
**Observation**: Some OPERATIONAL rules were really TACTICAL (implementation details)
**Problem**: OPERATIONAL should be processes, TACTICAL should be specific techniques
- inst_021: Document API-Model-Controller flow (technique, not process)
- inst_059: Write hook workaround (specific workaround, not general practice)
- inst_061: Hook approval persistence (UI behavior, not workflow)
**Lesson**: Classify by nature of rule, not perceived importance
**Action**: Reclassified inst_021, inst_059, inst_061 as TACTICAL
### 8. Coverage Gaps Emerge Over Time
**Observation**: Framework grew from 6 documented components to full implementation, but rules didn't keep pace
**Timeline**:
- Components documented in Maintenance Guide
- Implementation built in services/
- Hook system added for enforcement
- **But**: Rules still referenced "use framework actively" (inst_007 from early sessions)
**Lesson**: Periodic audits essential as systems evolve
**Action**: Made governance audit a recurring practice (quarterly recommended)
---
## Metrics
### Before Audit
- **Total Rules**: 54
- **Active Rules**: 54
- **Overlapping Rules**: 7 (13% of total)
- **Coverage Gaps**: 5 critical areas (framework usage, session init, git, environment verification, testing)
- **Vague Rules**: 3 (6% of total)
- **Misclassified Rules**: 3 (6% of total)
- **Persistence Distribution**: 94% HIGH, 4% MEDIUM, 2% LOW
### After Implementation
- **Total Rules**: 68 (54 active + 14 new/consolidated)
- **Active Rules**: 56
- **Overlapping Rules**: 0 (0%)
- **Coverage Gaps**: 0 (all filled)
- **Vague Rules**: 0 (all enhanced with specifics)
- **Misclassified Rules**: 0 (all corrected)
- **Persistence Distribution**: 91% HIGH, 7% MEDIUM, 2% LOW (better balance)
### Quality Improvements
- **Clarity**: +35% (vague rules eliminated, specific guidance added)
- **Coverage**: +100% (all critical gaps filled)
- **Efficiency**: +15% (overlaps removed, cognitive load reduced)
- **Enforceability**: +40% (actionable requirements, clear verification)
---
## New Rules Created
### Consolidated Rules (4 rules)
1. **inst_008_CONSOLIDATED** (CSP and Security Headers)
- Merged: inst_008, inst_044, inst_048
- Quadrant: SYSTEM | Persistence: HIGH
- Impact: Single source of truth for CSP compliance
2. **inst_020_CONSOLIDATED** (Deployment Permissions)
- Merged: inst_020, inst_022
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: Unified deployment permission requirements
3. **inst_041_CONSOLIDATED** (File Input Validation)
- Merged: inst_041, inst_042
- Quadrant: SYSTEM | Persistence: HIGH
- Impact: Comprehensive file/attachment security
4. **inst_063_CONSOLIDATED** (Public GitHub Management)
- Merged: inst_028, inst_062, inst_063
- Quadrant: STRATEGIC | Persistence: HIGH
- Impact: Complete public repository policy with weekly review
### Coverage Gap Rules (5 rules)
5. **inst_064** (Framework Component Usage)
- Replaces: inst_007
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: Explicit triggers for each of 6 framework components
- **CRITICAL**: Core framework enforcement
6. **inst_065** (Session Initialization)
- New requirement
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: Mandatory session-init.js at session start and after compaction
- **CRITICAL**: CLAUDE.md compliance
7. **inst_066** (Git Commit Conventions)
- New requirement
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: Conventional commit format with Claude Code attribution
8. **inst_067** (Environment Verification)
- New requirement
- Quadrant: SYSTEM | Persistence: HIGH
- Impact: Prevents 27027-type pattern recognition failures
- **CRITICAL**: Protection against bias
9. **inst_068** (Test Execution Requirements)
- New requirement
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: When to run tests, how to handle failures
### Split Rules (5 rules)
10. **inst_024a** (Background Process Cleanup)
11. **inst_024b** (Database Sync Verification)
12. **inst_024c** (Git State Documentation)
13. **inst_024d** (Temporary Artifact Cleanup)
14. **inst_024e** (Handoff Document Creation)
- Split from: inst_024
- Quadrant: OPERATIONAL | Persistence: HIGH
- Impact: Granular closedown enforcement, checkboxes for each step
---
## Tools Created
### 1. Audit Implementation Script
**File**: `scripts/apply-governance-audit-2025-10-21.js`
**Purpose**: Apply all audit recommendations automatically
**Capabilities**:
- Deprecate 12 overlapping rules
- Add 4 consolidated rules
- Add 5 new coverage rules
- Add 5 split rules
- Adjust persistence levels and quadrants
- Enhance vague rules with specifics
- Update version from 3.5 → 3.6
- Recalculate statistics
- Create backup before changes
**Output**: Comprehensive summary with before/after statistics
### 2. Database Sync Script
**File**: `scripts/sync-instructions-to-db.js`
**Purpose**: Maintain consistency between instruction-history.json and MongoDB
**Capabilities**:
- Insert new rules
- Update existing rules
- Deactivate removed rules
- Preserve metadata (parameters, deprecation reasons, adjustment history)
- Validate counts match
- Report sync statistics
**Usage**: Run after any changes to instruction-history.json
---
## Process Improvements
### Before This Session
1. Edit instruction-history.json manually
2. Hope changes sync somehow
3. No verification mechanism
4. No audit trail for rule changes
5. Overlaps discovered accidentally
6. Coverage gaps found when failures occur
### After This Session
1. **Audit Process**: Systematic review against project documentation
2. **Migration Scripts**: Automated application of changes
3. **Sync Scripts**: Reliable file-to-database consistency
4. **Verification**: Count matching, active/inactive checks
5. **Audit Trail**: Deprecation reasons, adjustment history preserved
6. **Documentation**: Comprehensive audit reports with metrics
### Recommended Ongoing Process
1. **Quarterly Audits**: Review governance rules vs current practices
2. **Post-Incident Reviews**: Add rules when failures occur
3. **Sync After Changes**: Run sync-instructions-to-db.js
4. **Version Increments**: Bump version on rule changes
5. **Backup First**: Scripts now create automatic backups
---
## Recommendations for Future Sessions
### 1. Use inst_064 (Framework Components) IMMEDIATELY
**What**: inst_064 specifies when to use each framework component
**When to Reference**:
- Session start: Use ContextPressureMonitor for baseline
- User gives instruction: Use InstructionPersistenceClassifier
- Before DB/config changes: Use CrossReferenceValidator
- Before values decisions: Use BoundaryEnforcer
- Complex operations (3+ files): Use MetacognitiveVerifier
- Values conflicts: Use PluralisticDeliberationOrchestrator
**Verification**: Update .claude/session-state.json after each component use
### 2. Follow inst_065 (Session Initialization) Protocol
**What**: Mandatory session initialization at start and after compaction
**Steps**:
1. Run `node scripts/session-init.js`
2. Report server status (curl health endpoint)
3. Report framework statistics
4. Report MongoDB status
5. BLOCK work until complete
**Why**: Ensures framework operational before work begins
### 3. Run Quarterly Governance Audits
**Schedule**: Every 3 months or after major framework changes
**Process**:
1. Review all active rules
2. Check against current CLAUDE.md and Maintenance Guide
3. Identify overlaps and gaps
4. Create audit report
5. Implement recommendations
6. Update version number
7. Sync to database
8. Document learnings
**Tools**: Use GOVERNANCE_RULES_AUDIT template as starting point
### 4. Create ADRs for Major Governance Changes
**What**: Architecture Decision Records for governance rule changes
**When**:
- Consolidating multiple rules
- Creating new critical rules
- Changing framework architecture
- Resolving rule conflicts
**Format**: See ADR-001 (to be created)
### 5. Monitor Framework Fade
**What**: Framework components not being used = CRITICAL FAILURE
**Detection**:
- .claude/session-state.json shows component staleness
- No ContextPressureMonitor updates in 50k+ tokens
- Explicit instructions given but not classified
- Major changes without cross-reference validation
**Recovery**: Immediate pressure check, review recent actions, apply framework retroactively if possible
---
## Session Artifacts
### Files Created
1. `docs/governance/GOVERNANCE_RULES_AUDIT_2025-10-21.md` (comprehensive audit report)
2. `docs/governance/GOVERNANCE_LEARNINGS_2025-10-21.md` (this document)
3. `scripts/apply-governance-audit-2025-10-21.js` (migration script)
4. `scripts/sync-instructions-to-db.js` (ongoing sync tool)
### Files Modified
1. `.claude/instruction-history.json` (version 3.5 → 3.6, 54 → 68 total instructions, 54 → 56 active)
2. `.claude/instruction-history.json.backup-3.5-*` (automatic backup created)
### Database Changes
1. MongoDB governanceRules collection: 55 → 71 total rules, 54 → 56 active rules
2. 16 new rules inserted
3. 52 existing rules updated
4. 12 rules deactivated with deprecation reasons
---
## Conclusion
This session demonstrated the value of systematic governance audits. By identifying and fixing overlaps, gaps, and vagueness, we significantly improved the enforceability and clarity of the Tractatus framework.
**Key Takeaway**: Documentation without enforcement is aspirational. Enforcement without clarity is ineffective. Both are required for robust governance.
**Impact**: Framework now has complete coverage of critical requirements with zero redundancy, enabling reliable autonomous operation within well-defined boundaries.
**Next Steps**:
1. Create ADR for public release process (Priority C)
2. Apply learnings to production deployment (Priority D)
3. Schedule quarterly audit for 2026-01-21
---
**Session Statistics**:
- Token Usage: ~86,000 / 200,000 (43% of budget)
- Time Investment: ~2 hours
- Rules Analyzed: 54
- Rules Created/Modified: 30
- Quality Improvement: +40%
- Coverage Improvement: +100%
**ROI**: High - Critical enforcement gaps filled, framework significantly strengthened

889
docs/governance/GOVERNANCE_RULES_AUDIT_2025-10-21.md
View file

@ -1,889 +0,0 @@
# Governance Rules Audit Report
**Date**: 2025-10-21
**Session**: 2025-10-07-001 (continued)
**Version**: 3.5 (54 active instructions)
---
## Executive Summary
This audit reviews all 54 active governance rules in `.claude/instruction-history.json` for:
- Appropriateness (fit for purpose)
- Completeness (coverage of critical areas)
- Specificity (clear, actionable guidance)
- Overlaps (redundancy/conflicts)
- Effectiveness (optimal structure for Claude Code enforcement)
**Key Findings**:
- ✅ **Strong areas**: Security (13 rules), deployment (6 rules), framework discipline (8 rules)
- ⚠️ **Overlaps identified**: 7 rules with partial redundancy
- ❌ **Coverage gaps**: 5 critical areas not covered by rules
- 🔧 **Recommendations**: Consolidate 7 rules → 3, split 2 rules → 4, create 5 new rules
---
## Methodology
### Sources Analyzed
1. `.claude/instruction-history.json` (54 active instructions)
2. `CLAUDE.md` (session start requirements)
3. `CLAUDE_Tractatus_Maintenance_Guide.md` (comprehensive reference)
4. Previous session handoff documents
5. Framework enforcement requirements
### Evaluation Criteria
- **Appropriateness**: Does rule address real need? Is it still relevant?
- **Completeness**: Does rule cover all necessary cases?
- **Specificity**: Is rule clear and actionable?
- **Persistence Level**: Is HIGH/MEDIUM/LOW correctly assigned?
- **Quadrant Classification**: Is SYSTEM/STRATEGIC/OPERATIONAL/TACTICAL correct?
- **Overlap/Conflict**: Does rule duplicate or contradict other rules?
---
## Distribution Analysis
### Current Distribution
- **SYSTEM**: 18 rules (33%) - Infrastructure, security, technical requirements
- **STRATEGIC**: 12 rules (22%) - Project goals, quality standards, governance
- **OPERATIONAL**: 21 rules (39%) - Day-to-day processes, workflows
- **TACTICAL**: 3 rules (6%) - Specific techniques, workarounds
### Persistence Distribution
- **HIGH**: 51 rules (94%) - Permanent across sessions
- **MEDIUM**: 2 rules (4%) - Session-specific, important
- **LOW**: 1 rule (2%) - Temporary guidance
### Assessment
- ✅ Distribution generally appropriate
- ⚠️ HIGH persistence may be over-used (51/54 = 94%)
- ⚠️ TACTICAL under-represented (3/54 = 6%)
- ⚠️ Some OPERATIONAL rules should be TACTICAL (implementation details)
---
## Overlaps & Redundancies
### 1. Security Header Rules (3 rules → consolidate to 1)
**inst_008**: CSP compliance (no inline handlers/scripts)
**inst_044**: Security headers (CSP, HSTS, X-Frame-Options, etc.)
**inst_048**: Pre-tool hook validators must check CSP compliance
**Issue**: Three rules covering CSP with partial overlap
**Recommendation**: Consolidate into single comprehensive security rule
```
PROPOSED: inst_008_CONSOLIDATED
Text: "ALL HTML/JS must comply with Content Security Policy (no inline handlers, no inline scripts). ALL HTTP responses MUST include security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy). Pre-tool hook validators MUST check CSP compliance before allowing edits."
Persistence: HIGH
Quadrant: SYSTEM
Scope: PERMANENT
```
**Action**: Merge inst_008, inst_044, inst_048 → inst_008_CONSOLIDATED
**Result**: 3 rules → 1 rule, clearer enforcement
### 2. Deployment Permission Rules (2 rules → consolidate to 1)
**inst_020**: File permissions must be correct before deployment (644/755)
**inst_022**: Deployment scripts MUST include automated permission correction
**Issue**: Overlapping coverage of same problem
**Recommendation**: Merge into single deployment permissions rule
```
PROPOSED: inst_020_CONSOLIDATED
Text: "Web deployments MUST ensure correct permissions (public HTML/CSS/JS: 644, scripts: 755, admin: 750). ALL deployment scripts (rsync, scp, git pull) MUST include automated post-deployment permission correction. Verify with ls -la before declaring deployment complete."
Persistence: HIGH
Quadrant: OPERATIONAL
Scope: PERMANENT
```
**Action**: Merge inst_020, inst_022 → inst_020_CONSOLIDATED
**Result**: 2 rules → 1 rule, single source of truth
### 3. File Upload Security Rules (2 rules → consolidate to 1)
**inst_041**: File uploads must be validated (type, size, content)
**inst_042**: Email attachments must be validated
**Issue**: Both cover file/attachment validation with similar requirements
**Recommendation**: Consolidate into comprehensive input validation rule
```
PROPOSED: inst_041_CONSOLIDATED
Text: "ALL file inputs (uploads, email attachments, user-provided files) MUST be validated: (1) File type whitelist, (2) Size limits, (3) Content scanning for malware/XSS, (4) Secure storage (GridFS encrypted), (5) Access control (authenticated only). Reject and log suspicious files per inst_046."
Persistence: HIGH
Quadrant: SYSTEM
Scope: PERMANENT
```
**Action**: Merge inst_041, inst_042 → inst_041_CONSOLIDATED
**Result**: 2 rules → 1 rule, unified validation approach
### 4. MongoDB Connection Rules (partial overlap)
**inst_001**: MongoDB on port 27017 for tractatus_dev
**inst_058**: Sync between JSON config and MongoDB requires Mongoose enum validation
**Issue**: Partial overlap - both address MongoDB but different aspects
**Recommendation**: Keep separate, clarify distinction in notes
**Action**: Update inst_001 notes to reference inst_058 for sync requirements
**Result**: Clarified relationship, no merge needed
### Summary of Overlaps
- **7 rules identified with overlaps**
- **Consolidation saves**: 4 rules (54 → 50)
- **Benefit**: Clearer enforcement, less cognitive load
---
## Coverage Gaps
### 1. Framework Component Usage Requirements ❌ NOT COVERED
**Gap**: CLAUDE_Maintenance_Guide.md specifies 6 mandatory components, but no rule enforces their usage
**Components Missing Coverage**:
1. ContextPressureMonitor (inst_006 mentions handoff, not continuous usage)
2. InstructionPersistenceClassifier (no rule requiring classification)
3. CrossReferenceValidator (no rule requiring validation)
4. BoundaryEnforcer (inst_005 mentions approval, not component)
5. MetacognitiveVerifier (no rule for when to use)
6. PluralisticDeliberationOrchestrator (no rule for activation)
**Current State**:
- inst_006: Only mentions ContextPressureMonitor for handoff
- inst_007: Generic "use framework actively" (too vague)
- inst_051: Automated pressure checks at milestones (partial coverage)
**Recommendation**: Create comprehensive framework component usage rule
```
PROPOSED: inst_064 - Framework Component Usage
Text: "Framework components MUST be actively used throughout sessions:
(1) ContextPressureMonitor: At session start, 50k/100k/150k tokens, after complex operations
(2) InstructionPersistenceClassifier: When user gives explicit instruction
(3) CrossReferenceValidator: Before DB schema, config, architectural changes
(4) BoundaryEnforcer: Before values/privacy/ethical decisions
(5) MetacognitiveVerifier: For operations with 3+ files or 5+ steps
(6) PluralisticDeliberationOrchestrator: When BoundaryEnforcer flags values conflict
Framework fade (components not used) = CRITICAL FAILURE. Update .claude/session-state.json after each component use."
Persistence: HIGH
Quadrant: OPERATIONAL
Scope: PERMANENT
```
**Impact**: HIGH - This is the core enforcement gap for the framework
### 2. Session Initialization Requirements ❌ PARTIALLY COVERED
**Gap**: CLAUDE.md requires `node scripts/session-init.js` IMMEDIATELY at session start and after compaction, but no rule enforces this
**Current State**:
- No rule exists for session-init.js requirement
- inst_024 covers session closedown, but not startup
**Recommendation**: Create session startup rule
```
PROPOSED: inst_065 - Session Initialization
Text: "MANDATORY at session start and after compaction: Run 'node scripts/session-init.js', then report (1) Server status (curl http://localhost:9000/health), (2) Framework stats (session ID, active instructions, version), (3) MongoDB status (active rules count). BLOCK session work until initialization complete and results reported to user."
Persistence: HIGH
Quadrant: OPERATIONAL
Scope: PERMANENT
```
**Impact**: HIGH - Required by CLAUDE.md, currently not enforced
### 3. Git Commit Message Format ❌ NOT COVERED
**Gap**: CLAUDE_Maintenance_Guide.md specifies conventional commits (feat:, fix:, docs:, etc.), but no rule enforces this
**Current State**:
- No rule for commit message format
- Maintenance Guide documents convention but doesn't enforce
**Recommendation**: Create git conventions rule
```
PROPOSED: inst_066 - Git Commit Conventions
Text: "ALL git commits MUST use conventional commit format: 'type(scope): description'
Types: feat, fix, docs, refactor, test, chore
Include Claude Code attribution footer:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
NEVER use 'git commit -i' (interactive mode not supported). When pre-commit hooks modify files, verify authorship before amending commits."
Persistence: HIGH
Quadrant: OPERATIONAL
Scope: PERMANENT
```
**Impact**: MEDIUM - Improves git history quality, aligns with project standards
### 4. Port/Database Verification Before Actions ❌ NOT COVERED
**Gap**: Multiple incidents of wrong port/database usage, but no rule requires verification
**Examples**:
- 27027 incident (used 27017 instead of 27027)
- Production port confusion (9000 vs other ports)
**Recommendation**: Create environment verification rule
```
PROPOSED: inst_067 - Environment Verification
Text: "BEFORE database operations or port-specific commands: (1) VERIFY current environment (local vs production), (2) VERIFY correct port/database from explicit user instruction or CLAUDE.md defaults (tractatus_dev:27017 local, tractatus_prod:27017 production, app:9000), (3) If user specifies non-standard port (e.g., 27027), USE EXACT VALUE - do NOT autocorrect to standard defaults. Pattern recognition bias for standard ports is a known 27027 failure mode."
Persistence: HIGH
Quadrant: SYSTEM
Scope: PERMANENT
```
**Impact**: HIGH - Prevents 27027-type failures
### 5. Test Execution Requirements ❌ NOT COVERED
**Gap**: No rule specifies when tests must be run or how to handle test failures
**Current State**:
- inst_054 mentions deployment checklist but not test execution policy
- No guidance on test-driven development expectations
**Recommendation**: Create testing requirements rule
```
PROPOSED: inst_068 - Test Execution Requirements
Text: "Run tests in these scenarios: (1) Before git commits (if tests exist for modified area), (2) Before deployments (full test suite), (3) After refactoring (affected tests). Test failures BLOCK commits/deployments unless user explicitly approves proceeding. When creating new features, ask user if tests should be written (don't assume). Report test results: passed/failed/skipped counts."
Persistence: HIGH
Quadrant: OPERATIONAL
Scope: PERMANENT
```
**Impact**: MEDIUM - Improves code quality, aligns with world-class standard
### Summary of Coverage Gaps
- **5 critical gaps identified**
- **Proposed**: 5 new rules (inst_064 through inst_068)
- **Impact**: HIGH for 3 rules, MEDIUM for 2 rules
- **Result**: Framework enforcement significantly improved
---
## Specificity Issues
### Rules Too Vague
#### inst_007: "Use Tractatus governance framework actively in all sessions"
**Issue**: Too generic, doesn't specify WHAT to do
**Recommendation**: REPLACE with inst_064 (Framework Component Usage) which specifies exactly when to use each component
#### inst_040: "When user says 'all', Claude MUST enumerate exactly"
**Issue**: Good intent, but "enumerate exactly" is vague
**Recommendation**: Enhance with examples
```
ENHANCED: inst_040
Text: "When user says 'all' (e.g., 'update all pages', 'fix all instances', 'check all files'), Claude MUST: (1) Use Glob/Grep to find ALL matches, (2) List every item found with file:line references, (3) Confirm with user before proceeding, (4) Track completion of each item. NEVER assume 'all' means 'a few examples' or 'the ones I found first'."
```
### Rules Too Narrow
#### inst_059: "When creating new files that may trigger Write hook validation..."
**Issue**: Very specific workaround for hook issue, likely temporary
**Recommendation**: Consider lowering persistence to LOW (currently MEDIUM)
#### inst_060: "When using sed for global replacements, verify won't cascade..."
**Issue**: Extremely specific (sed cascading), already marked LOW persistence
**Recommendation**: KEEP as-is (appropriately marked LOW)
### Rules Missing Action Guidance
#### inst_047: "NEVER dismiss user requests by claiming 'too hard'"
**Issue**: Says what NOT to do, but not what TO do instead
**Recommendation**: Enhance with positive guidance
```
ENHANCED: inst_047
Text: "NEVER dismiss, downplay, or avoid user requests by claiming 'too hard', 'too complex', 'beyond capabilities'. When facing difficult requests: (1) Acknowledge complexity honestly, (2) Break into smaller steps, (3) Identify blockers explicitly, (4) Propose alternative approaches, (5) Ask user for priorities/trade-offs. If truly impossible, explain technical limitations with evidence, not vague dismissal."
```
### Summary of Specificity Issues
- **3 rules too vague** (inst_007 → replace, inst_040 → enhance)
- **2 rules too narrow** (inst_059 → lower persistence, inst_060 → keep as-is)
- **1 rule missing action guidance** (inst_047 → enhance)
- **Result**: More actionable, clearer enforcement
---
## Persistence Level Issues
### Rules Potentially Over-Persisted (HIGH → MEDIUM)
#### inst_011: "Differentiate technical docs from general content"
**Current**: HIGH, PROJECT scope
**Issue**: This is an implementation detail, not a permanent requirement
**Recommendation**: Lower to MEDIUM persistence
#### inst_021: "Document API-Model-Controller flow when implementing features"
**Current**: HIGH, PROJECT scope
**Issue**: Development practice, useful but not critical
**Recommendation**: Lower to MEDIUM persistence
### Rules Potentially Under-Persisted (MEDIUM → HIGH)
#### inst_059: "Workaround for Write hook validation"
**Current**: MEDIUM, PROJECT scope
**Issue**: If hooks are staying, this workaround is permanent knowledge
**Recommendation**: Raise to HIGH if hooks are permanent, otherwise DELETE when hooks improved
### Summary of Persistence Issues
- **2 rules over-persisted** (inst_011, inst_021 → MEDIUM)
- **1 rule under-persisted** (inst_059 → HIGH or DELETE)
- **Result**: Better signal-to-noise ratio
---
## Rules Requiring Splits
### inst_024: Session Closedown Protocol (TOO BROAD)
**Current**: Single rule covering 5 distinct closedown steps
**Issue**: Each step deserves separate attention/validation
**Recommendation**: Split into focused rules
```
inst_024a - Background Process Cleanup
Text: "Before session handoff: Kill background processes (npm, jest, node). Use ps aux | grep to find, pkill to terminate. Verify with ps aux again. Update session-state.json with cleanup timestamp."
Persistence: HIGH
Quadrant: OPERATIONAL
inst_024b - Database Sync Verification
Text: "Before session handoff: Verify instruction-history.json synced to MongoDB. If changes exist, run sync script. Report sync status in handoff document."
Persistence: HIGH
Quadrant: OPERATIONAL
inst_024c - Git State Documentation
Text: "Before session handoff: Document git status (branch, commits ahead/behind, working tree status). Include in handoff with explanations for untracked files."
Persistence: HIGH
Quadrant: OPERATIONAL
inst_024d - Temporary Artifact Cleanup
Text: "Before session handoff: Clean temporary artifacts (.memory-test/, test databases, lock files if stale). Document what was cleaned and what was intentionally kept."
Persistence: HIGH
Quadrant: OPERATIONAL
inst_024e - Handoff Document Creation
Text: "Create handoff document as OPTIMAL_STARTUP_PROMPT with: (1) System status, (2) Completed/pending tasks with file:line references, (3) Known issues, (4) User decisions needed, (5) Ready-to-use TodoWrite JSON. STOP work immediately after handoff creation - signals NEW session intent."
Persistence: HIGH
Quadrant: OPERATIONAL
```
**Action**: Split inst_024 → inst_024a/b/c/d/e
**Result**: 1 rule → 5 rules, clearer enforcement, easier to verify
### inst_054: Pre-Deployment Checklist (TOO BROAD)
**Current**: Single rule covering 5 deployment checks
**Issue**: Each check is independently verifiable
**Recommendation**: Keep as single rule BUT enhance with numbered checklist format
```
ENHANCED: inst_054
Text: "PRE-DEPLOYMENT CHECKLIST (run in order):
□ 1. CSP Compliance Check [AUTOMATED via hook]
□ 2. Local Server Test (curl http://localhost:9000/health → 200 OK)
□ 3. Comprehensive Testing (npm test → all pass)
□ 4. Permission Verification (ls -la → correct 644/755)
□ 5. Git Status Clean (no uncommitted changes)
Mark each checkbox before proceeding to next. BLOCK deployment if any step fails."
Persistence: HIGH
Quadrant: OPERATIONAL
```
**Action**: Enhance inst_054 with checklist format
**Result**: Better verification, no additional rules needed
### Summary of Split Requirements
- **1 rule requires split** (inst_024 → 5 rules)
- **1 rule enhanced with checklist** (inst_054)
- **Result**: More granular enforcement, clearer verification
---
## Quadrant Misclassifications
### inst_021: API-Model-Controller Documentation
**Current**: OPERATIONAL
**Issue**: This is an implementation detail, should be TACTICAL
**Recommendation**: Reclassify as TACTICAL
### inst_059: Write Hook Workaround
**Current**: Not explicitly classified (appears OPERATIONAL)
**Issue**: This is a specific technique, should be TACTICAL
**Recommendation**: Reclassify as TACTICAL
### inst_061: Hook Approval Persistence
**Current**: Not explicitly classified (appears OPERATIONAL)
**Issue**: User interface behavior, should be TACTICAL
**Recommendation**: Reclassify as TACTICAL
### Summary of Quadrant Issues
- **3 rules misclassified** (all OPERATIONAL → TACTICAL)
- **Result**: Better alignment with quadrant definitions
---
## Rules Requiring Updates
### inst_009: Email Services Status
**Current**: "Email deferred until production launch"
**Issue**: Notes say "Updated 2025-10-21: Stripe fully implemented and active"
**Recommendation**: Update text to reflect current state
```
UPDATED: inst_009
Text: "Stripe payment processing is ACTIVE (test keys configured). Email services (verification emails, donation receipts) are deferred until production launch. ProtonBridge email integration is Phase 2+."
```
### inst_028: Public GitHub Sync Rules
**Current**: "ONLY docs/research to public GitHub"
**Issue**: Conflicts with inst_063 which provides more detailed guidance
**Recommendation**: Merge with inst_063
```
CONSOLIDATED: inst_063 (absorbs inst_028)
Text: "Public GitHub (tractatus-framework) must remain implementation-focused. Prohibited without explicit approval: (1) Governance research documents, (2) Deliberation guides, (3) Theoretical frameworks, (4) Project-specific documentation. Allowed: (1) Technical implementation docs, (2) API references, (3) Code examples, (4) Setup guides. README.md must be reviewed weekly and updated with material changes."
Persistence: HIGH
Quadrant: STRATEGIC
```
### inst_062: GitHub README.md Weekly Review
**Current**: "README reviewed weekly"
**Issue**: This is part of public repo management, should merge with inst_063
**Recommendation**: Already merged above in consolidated inst_063
### Summary of Update Requirements
- **3 rules need updates** (inst_009 text, inst_028/063 merge, inst_062 absorbed)
- **Result**: More accurate, less redundancy
---
## Comparison with CLAUDE.md
### CLAUDE.md Requirements Analysis
**Required by CLAUDE.md**:
1. ✅ MongoDB port 27017, database tractatus_dev (inst_001)
2. ✅ Application port 9000 (inst_002)
3. ✅ Project separation (inst_003)
4. ✅ World-class quality standard (inst_004)
5. ✅ Human approval for major decisions (inst_005)
6. ❌ **MISSING**: Session initialization requirement (`node scripts/session-init.js`)
7. ❌ **MISSING**: Framework statistics reporting requirement
8. ✅ Pre-approved commands for document workflow (covered in Maintenance Guide)
9. ✅ Framework components active (inst_007, but needs enhancement → inst_064)
10. ✅ Process management: systemd not pm2 (documented but no rule - low priority)
**Gap**: Session initialization (covered by proposed inst_065)
### CLAUDE_Maintenance_Guide.md Requirements Analysis
**Required by Maintenance Guide**:
1. ✅ Six framework components mandatory (inst_007 partial, needs inst_064)
2. ✅ 27027 failure prevention (inst_001 partial, needs inst_067)
3. ✅ ContextPressureMonitor usage at milestones (inst_051)
4. ❌ **MISSING**: InstructionPersistenceClassifier usage requirement
5. ❌ **MISSING**: CrossReferenceValidator usage requirement
6. ❌ **MISSING**: BoundaryEnforcer usage requirement
7. ❌ **MISSING**: MetacognitiveVerifier usage requirement
8. ❌ **MISSING**: PluralisticDeliberationOrchestrator usage requirement
9. ✅ Session handoff protocol (inst_024)
10. ✅ Git conventions (documented but needs inst_066)
11. ✅ Document workflow (covered by multiple rules)
12. ✅ Security requirements (inst_008, 012-015, 041-046)
13. ✅ Deployment requirements (inst_020, 022, 025, 054, 057)
**Gap**: Framework component usage (covered by proposed inst_064)
### Summary of CLAUDE.md/Maintenance Guide Gaps
- **2 critical gaps**: Session initialization, framework component usage
- **Both gaps covered** by proposed inst_064 and inst_065
- **Result**: Full alignment with project documentation
---
## Final Recommendations
### Immediate Actions (High Priority)
#### 1. Consolidate Overlapping Rules
- ✅ Merge inst_008 + inst_044 + inst_048 → inst_008_CONSOLIDATED (CSP/security headers)
- ✅ Merge inst_020 + inst_022 → inst_020_CONSOLIDATED (deployment permissions)
- ✅ Merge inst_041 + inst_042 → inst_041_CONSOLIDATED (file upload validation)
- ✅ Merge inst_028 + inst_062 + inst_063 → inst_063_CONSOLIDATED (public GitHub management)
**Result**: 54 → 50 rules
#### 2. Create Missing Critical Rules
- ✅ inst_064: Framework Component Usage (HIGH priority - core framework)
- ✅ inst_065: Session Initialization (HIGH priority - CLAUDE.md requirement)
- ✅ inst_066: Git Commit Conventions (MEDIUM priority - code quality)
- ✅ inst_067: Environment Verification (HIGH priority - 27027 prevention)
- ✅ inst_068: Test Execution Requirements (MEDIUM priority - quality standard)
**Result**: 50 → 55 rules
#### 3. Split Overly Broad Rules
- ✅ Split inst_024 → inst_024a/b/c/d/e (session closedown)
**Result**: 55 → 59 rules
#### 4. Enhance Vague Rules
- ✅ Enhance inst_040 (enumerate 'all' with examples)
- ✅ Enhance inst_047 (positive guidance for difficult requests)
- ✅ Enhance inst_054 (checklist format)
**Result**: 59 rules (same count, improved clarity)
#### 5. Fix Persistence Levels
- ✅ Lower inst_011, inst_021 from HIGH → MEDIUM
- ✅ Delete inst_007 (replaced by inst_064)
**Result**: 59 → 58 rules
#### 6. Fix Quadrant Classifications
- ✅ Reclassify inst_021, inst_059, inst_061 from OPERATIONAL → TACTICAL
**Result**: 58 rules (same count, correct classification)
#### 7. Update Outdated Rules
- ✅ Update inst_009 text (Stripe status)
**Result**: 58 rules (same count, accurate information)
### Final Count
- **Starting**: 54 rules
- **After consolidation**: -4 rules (54 → 50)
- **After new rules**: +5 rules (50 → 55)
- **After splits**: +4 rules (55 → 59)
- **After deletions**: -1 rule (59 → 58)
- **FINAL**: **58 rules**
**Net change**: +4 rules (7% increase)
**Quality improvement**: Significant (overlaps removed, gaps filled, clarity enhanced)
### Implementation Plan
#### Phase 1: Consolidation (Immediate)
1. Create consolidated rules (inst_008, inst_020, inst_041, inst_063)
2. Mark original rules as `active: false` with deprecation notes
3. Update session-state.json with consolidation timestamp
#### Phase 2: New Rules (Immediate)
1. Create inst_064 (Framework Component Usage)
2. Create inst_065 (Session Initialization)
3. Create inst_066 (Git Commit Conventions)
4. Create inst_067 (Environment Verification)
5. Create inst_068 (Test Execution Requirements)
#### Phase 3: Splits (Immediate)
1. Create inst_024a/b/c/d/e (split closedown protocol)
2. Mark inst_024 as deprecated with reference to split rules
#### Phase 4: Enhancements (Next Session)
1. Enhance inst_040, inst_047, inst_054 with improved text
2. Update inst_009 text
3. Adjust persistence levels (inst_011, inst_021)
4. Reclassify quadrants (inst_021, inst_059, inst_061)
#### Phase 5: Verification (Next Session)
1. Run framework tests with new rules
2. Verify CrossReferenceValidator handles consolidated rules
3. Test session-init.js with inst_065 active
4. Update documentation to reference new rule IDs
---
## Metrics
### Before Audit
- **Total Rules**: 54
- **Overlapping Rules**: 7 (13%)
- **Coverage Gaps**: 5 critical areas
- **Vague Rules**: 3 (6%)
- **Misclassified Rules**: 3 (6%)
### After Implementation
- **Total Rules**: 58 (+4)
- **Overlapping Rules**: 0 (0%)
- **Coverage Gaps**: 0 (all filled)
- **Vague Rules**: 0 (all enhanced)
- **Misclassified Rules**: 0 (all corrected)
### Quality Improvement
- **Clarity**: +35% (vague rules eliminated, specific guidance added)
- **Coverage**: +100% (all gaps filled)
- **Efficiency**: +15% (overlaps removed, cognitive load reduced)
- **Enforceability**: +40% (actionable requirements, clear verification)
---
## Appendix A: Consolidated Rule Texts
### inst_008_CONSOLIDATED (CSP and Security Headers)
```json
{
"id": "inst_008_CONSOLIDATED",
"text": "ALL HTML/JS must comply with Content Security Policy: no inline event handlers (onclick, onload, etc.), no inline scripts, no inline styles. ALL HTTP responses MUST include comprehensive security headers: Content-Security-Policy, Strict-Transport-Security, X-Frame-Options (DENY), X-Content-Type-Options (nosniff), Referrer-Policy (strict-origin-when-cross-origin). Pre-tool execution hook validators (validate-file-write.js, validate-file-edit.js) MUST check CSP compliance before allowing edits and provide specific violation details if blocked.",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "CONSOLIDATED from inst_008, inst_044, inst_048. Single source of truth for CSP and security header requirements. Prevents CSP violations and security header omissions.",
"deprecates": ["inst_008", "inst_044", "inst_048"],
"active": true
}
```
### inst_020_CONSOLIDATED (Deployment Permissions)
```json
{
"id": "inst_020_CONSOLIDATED",
"text": "Web application deployments MUST ensure correct file permissions before going live. Public-facing HTML/CSS/JS: 644 (rw-r--r--), executable scripts: 755 (rwxr-xr-x), admin directories: 750 (rwxr-x---). ALL deployment scripts (rsync, scp, git pull) MUST include automated post-deployment permission correction commands. Verify with 'ls -la' before declaring deployment complete. Permission errors are recurring deployment failures - automated correction is mandatory.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "CONSOLIDATED from inst_020, inst_022. Prevents public access to admin directories and execution of static files. Recurring issue required automation mandate.",
"deprecates": ["inst_020", "inst_022"],
"active": true
}
```
### inst_041_CONSOLIDATED (File Input Validation)
```json
{
"id": "inst_041_CONSOLIDATED",
"text": "ALL file inputs (web uploads, email attachments, user-provided files) MUST be validated before processing: (1) File type whitelist validation (reject executables, scripts), (2) Size limits enforced, (3) Content scanning for malware/XSS payloads, (4) Secure storage (GridFS with encryption), (5) Access control (authenticated users only, role-based permissions). Reject and log all suspicious files per inst_046 (security event logging). Never trust client-provided MIME types - verify file signatures.",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "CONSOLIDATED from inst_041, inst_042. Comprehensive file/attachment security validation. Part of security vetting framework.",
"deprecates": ["inst_041", "inst_042"],
"active": true
}
```
### inst_063_CONSOLIDATED (Public GitHub Management)
```json
{
"id": "inst_063_CONSOLIDATED",
"text": "Public GitHub repository (tractatus-framework) must remain implementation-focused. Prohibited without explicit approval: (1) Governance research documents, (2) Pluralistic deliberation guides, (3) Theoretical frameworks, (4) Project-specific internal documentation, (5) Business strategy documents. Allowed: (1) Technical implementation documentation, (2) API reference guides, (3) Code examples and tutorials, (4) Installation/setup guides, (5) Contribution guidelines. README.md must be reviewed weekly and 'Last Updated' date updated when material changes occur. README is primary external interface - must be world-class and current.",
"quadrant": "STRATEGIC",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "CONSOLIDATED from inst_028, inst_062, inst_063. Created after bad actor incident where AI converted implementation docs to authoritarian governance guide. Prevents misrepresentation of framework purpose.",
"deprecates": ["inst_028", "inst_062", "inst_063"],
"active": true
}
```
---
## Appendix B: New Rule Texts
### inst_064 (Framework Component Usage)
```json
{
"id": "inst_064",
"text": "Tractatus framework components MUST be actively used throughout sessions: (1) ContextPressureMonitor: At session start (baseline), 50k/100k/150k token milestones, after complex multi-file operations, after errors. (2) InstructionPersistenceClassifier: When user gives explicit instruction, configuration specifications, architectural constraints. (3) CrossReferenceValidator: Before database schema changes, configuration modifications, architectural decisions. (4) BoundaryEnforcer: Before privacy policy decisions, ethical trade-offs, values-sensitive content. (5) MetacognitiveVerifier: For operations with 3+ file modifications or 5+ sequential steps. (6) PluralisticDeliberationOrchestrator: When BoundaryEnforcer flags values conflict. Framework fade (components not being used) = CRITICAL FAILURE. Update .claude/session-state.json after each component use with timestamp and validation count.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "CRITICAL ENFORCEMENT GAP - Previously documented but not enforced as rule. Specifies exactly when each component must be used. Replaces vague inst_007.",
"replaces": ["inst_007"],
"active": true
}
```
### inst_065 (Session Initialization)
```json
{
"id": "inst_065",
"text": "MANDATORY at session start and immediately after conversation compaction: Run 'node scripts/session-init.js', then report to user: (1) Server status: curl -s http://localhost:9000/health | jq -r '.status' (expect 'ok'), (2) Framework statistics: session ID, active instructions count, version from .claude/session-state.json and .claude/instruction-history.json, (3) MongoDB status: active rules count from tractatus_dev database. BLOCK all session work until initialization complete and results reported to user. Output results in clean formatted summary before proceeding with any tasks.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Required by CLAUDE.md but not previously enforced as rule. Ensures framework operational before work begins. Critical for session continuity after compaction.",
"active": true
}
```
### inst_066 (Git Commit Conventions)
```json
{
"id": "inst_066",
"text": "ALL git commits MUST use conventional commit format: 'type(scope): description'. Types: feat (new feature), fix (bug fix), docs (documentation), refactor (code restructure), test (test additions), chore (maintenance). Include Claude Code attribution footer:\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\nCo-Authored-By: Claude <noreply@anthropic.com>\n\nNEVER use 'git commit -i' or 'git add -i' (interactive modes not supported). When pre-commit hooks modify files, verify commit authorship (git log -1 --format='%an %ae') before amending - NEVER amend other developers' commits.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Documented in Maintenance Guide but not enforced as rule. Improves git history quality and provides attribution transparency.",
"active": true
}
```
### inst_067 (Environment Verification)
```json
{
"id": "inst_067",
"text": "BEFORE database operations or port-specific commands: (1) VERIFY current environment (local vs production) from context, (2) VERIFY correct port/database from explicit user instruction OR CLAUDE.md defaults (local: tractatus_dev:27017 on port 9000, production: tractatus_prod:27017 on port 9000), (3) If user specifies non-standard port or database (e.g., port 27027, custom database name), USE EXACT VALUE FROM USER INSTRUCTION - do NOT autocorrect to standard defaults. Pattern recognition bias for standard ports/databases is a known 27027 failure mode where training data associations override explicit instructions. When in doubt, ask user to confirm environment.",
"quadrant": "SYSTEM",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Prevents 27027-type failures where pattern recognition overrides explicit user instructions. Critical for multi-environment operations.",
"active": true
}
```
### inst_068 (Test Execution Requirements)
```json
{
"id": "inst_068",
"text": "Run tests in these scenarios: (1) Before git commits if tests exist for modified code area, (2) Before all deployments (run full test suite), (3) After refactoring (run affected tests), (4) When user explicitly requests testing. Test failures BLOCK commits and deployments unless user explicitly approves proceeding with failing tests. When creating new features, ask user if tests should be written - do not assume test requirements. Report test results with counts: X passed, Y failed, Z skipped. Use 'npm test' for full suite or 'npm test -- <path>' for specific tests.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Aligns with world-class quality standard (inst_004). Prevents regressions and maintains code quality.",
"active": true
}
```
---
## Appendix C: Split Rule Texts
### inst_024a (Background Process Cleanup)
```json
{
"id": "inst_024a",
"text": "Before session handoff or closedown: Kill all background processes spawned during session (npm, jest, node, dev servers, file watchers). Use 'ps aux | grep -E \"npm|jest|node\"' to find processes, 'pkill -f <pattern>' to terminate. Verify cleanup with 'ps aux | grep -E \"npm|jest|node\"' again (should show no results except grep itself). Update .claude/session-state.json with cleanup timestamp and process count terminated.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Split from inst_024 for granular enforcement. Part of comprehensive closedown protocol.",
"part_of": "inst_024_series",
"active": true
}
```
### inst_024b (Database Sync Verification)
```json
{
"id": "inst_024b",
"text": "Before session handoff: Verify .claude/instruction-history.json changes are synced to MongoDB governanceRules collection. If instruction-history.json modified this session, run 'node scripts/sync-instructions-to-db.js' to sync. Compare counts: active instructions in JSON vs active rules in database. Report sync status in handoff document: 'Synced: X instructions → Y database rules' or 'Not needed: No changes this session'.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Split from inst_024 for granular enforcement. Ensures file-database consistency.",
"part_of": "inst_024_series",
"active": true
}
```
### inst_024c (Git State Documentation)
```json
{
"id": "inst_024c",
"text": "Before session handoff: Document complete git status: (1) Current branch, (2) Commits ahead/behind remote (git status shows 'Your branch is ahead of origin/main by X commits'), (3) Working tree status (clean vs untracked files), (4) Most recent commits (git log --oneline -5). Include in handoff document with explanations for any untracked files (e.g., 'untracked files are INTERNAL project files, NOT for public repo'). If working tree has uncommitted changes, explain why or commit before handoff.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Split from inst_024 for granular enforcement. Provides next session with clear git context.",
"part_of": "inst_024_series",
"active": true
}
```
### inst_024d (Temporary Artifact Cleanup)
```json
{
"id": "inst_024d",
"text": "Before session handoff: Clean temporary artifacts created during session: (1) .memory-test/ directory (if exists from testing), (2) Test databases (mongosh --eval 'db.dropDatabase()' on tractatus_test), (3) Stale lock files (check age - if hours old with no process, safe to delete), (4) Temporary scripts in /tmp/. Document what was cleaned and what was intentionally kept (e.g., 'package-lock.json kept - legitimate', 'mongod.lock kept - server running'). Do NOT delete legitimate lock files for running processes.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Split from inst_024 for granular enforcement. Prevents clutter accumulation across sessions.",
"part_of": "inst_024_series",
"active": true
}
```
### inst_024e (Handoff Document Creation)
```json
{
"id": "inst_024e",
"text": "Create session handoff document as OPTIMAL_STARTUP_PROMPT_<DATE>.md with: (1) Current system status (server, framework, database, git), (2) Completed tasks with file:line references and verification, (3) In-progress tasks with blockers and next steps, (4) Pending tasks prioritized by user importance, (5) Recent instruction additions/changes with rationale, (6) Known issues and gotchas, (7) Framework health assessment, (8) User decisions needed, (9) Ready-to-use TodoWrite JSON for next session, (10) Recommended startup sequence with exact commands. STOP ALL WORK IMMEDIATELY after creating handoff document - handoff signals NEW session intent, not continuation.",
"quadrant": "OPERATIONAL",
"persistence": "HIGH",
"temporal_scope": "PERMANENT",
"session_id": "2025-10-21-governance-audit",
"notes": "Split from inst_024 for granular enforcement. Core handoff creation with strict format requirements.",
"part_of": "inst_024_series",
"active": true
}
```
---
**END OF AUDIT REPORT**

176
scripts/add-security-rules-2025-10-21.js
View file

@ -1,176 +0,0 @@
#!/usr/bin/env node
/**
* Add Security Rules - Post-Breach Response
*
* Adds inst_069, inst_070, inst_071, inst_072 in response to
* Anthropic API key exposure incident on 2025-10-21
*/
const fs = require('fs');
const path = require('path');
const INSTRUCTION_FILE = path.join(__dirname, '../.claude/instruction-history.json');
console.log('═══════════════════════════════════════════════════════════');
console.log(' ADD SECURITY RULES - POST-BREACH RESPONSE');
console.log('═══════════════════════════════════════════════════════════\n');
// Read current data
console.log('📖 Reading current instruction-history.json...');
const data = JSON.parse(fs.readFileSync(INSTRUCTION_FILE, 'utf8'));
console.log(` Version: ${data.version}`);
console.log(` Instructions: ${data.instructions.length}`);
console.log(` Active: ${data.stats.active_instructions}\n`);
// Create backup
const backupFile = INSTRUCTION_FILE + '.backup-pre-security-rules-' + Date.now();
fs.copyFileSync(INSTRUCTION_FILE, backupFile);
console.log(`💾 Backup created: ${path.basename(backupFile)}\n`);
// Define new security rules
const newRules = [
{
id: 'inst_069',
text: 'ALL credentials, API keys, secrets, tokens, passwords in documentation MUST be redacted or use example-only values. NEVER include real production or development credentials in files committed to git. Required patterns: API keys: "sk-ant-api03-EXAMPLE-REDACTED-NEVER-USE", Stripe keys: "sk_live_EXAMPLE_REDACTED", "pk_live_EXAMPLE_REDACTED", Passwords: "REDACTED" or "your-password-here", Tokens: "your-token-here". BEFORE committing any file containing credential-like patterns: (1) Replace ALL real values with examples/redacted versions, (2) Run secret detection scan (gitleaks or detect-secrets), (3) Verify no actual credentials remain. If actual credentials needed for deployment, use: Environment variables (.env file, NOT committed), Secure secret management (HashiCorp Vault, AWS Secrets Manager), Deployment-specific configuration (NOT in git).',
quadrant: 'SYSTEM',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CRITICAL SECURITY REQUIREMENT - Created in response to Anthropic API key exposure incident on 2025-10-21. API key (sk-ant-api03-_xm...TwAA, ID 5043627, name: family-history-ocr) was committed to public repository in docs/STRIPE_LIVE_MODE_DEPLOYMENT.md at commit 31345d5c1abc8c8da9387d55494a1741f451f9a7. GitHub secret scanning detected and Anthropic revoked key automatically. This rule prevents recurrence by requiring ALL credentials to be redacted in documentation and enforcing secret detection scans before commits.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
security_critical: true,
incident_response: 'anthropic_api_key_exposure_2025_10_21'
}
},
{
id: 'inst_070',
text: 'ALL git commits MUST pass secret detection scan before being allowed. Use gitleaks or detect-secrets as pre-commit hook. Hook location: .git/hooks/pre-commit. Command: gitleaks detect --source . --verbose. Action: BLOCK commit if secrets detected. If legitimate secret-like pattern detected (false positive): (1) Verify it is NOT a real secret, (2) Add to .gitleaksignore with comment explaining why, (3) Get user approval before committing, (4) Document in commit message. NEVER bypass secret detection hook without explicit user approval.',
quadrant: 'SYSTEM',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CRITICAL SECURITY REQUIREMENT - Created in response to Anthropic API key exposure incident. Automated pre-commit hook prevents credentials from being committed to git in the first place. This is Layer 3 of defense-in-depth strategy (Prevention → Mitigation → Detection → Backstop → Recovery).',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
automation_required: true,
security_critical: true
}
},
{
id: 'inst_071',
text: 'PRE-DEPLOYMENT CHECKLIST (run in order):\n□ 1. CSP Compliance Check [AUTOMATED via hook]\n□ 2. Secret Detection Scan (gitleaks detect --source .)\n□ 3. Credential Audit (grep -r "sk-" "pk-" "secret" "password")\n□ 4. Local Server Test (curl http://localhost:9000/health → 200 OK)\n□ 5. Comprehensive Testing (npm test → all pass)\n□ 6. Permission Verification (ls -la → correct 644/755)\n□ 7. Git Status Clean (no uncommitted changes)\n□ 8. Public Repository Content Review (no internal docs)\nMark each checkbox before proceeding to next. BLOCK deployment if any step fails.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'ENHANCED from inst_054 - Added steps 2, 3, 8 in response to security incident. Step 2 (Secret Detection) and Step 3 (Credential Audit) provide redundant verification that no credentials are being deployed. Step 8 (Public Repository Content Review) ensures no internal documentation accidentally published. This is defense-in-depth approach.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
replaces: 'inst_054'
}
},
{
id: 'inst_072',
text: 'Implement defense-in-depth for credential protection: Layer 1 - Prevention: Never commit credentials to git. Layer 2 - Mitigation: Redact credentials in documentation. Layer 3 - Detection: Pre-commit secret scanning (automated). Layer 4 - Backstop: GitHub secret scanning (automatic on public repos). Layer 5 - Recovery: Credential rotation procedures documented. ALL security-sensitive operations must have multiple layers. If one layer fails, others should prevent catastrophic outcome. When creating deployment documentation: (1) Use environment variable names, not values, (2) Include credential rotation procedures, (3) Document secret management system (Vault, AWS Secrets Manager), (4) Never assume "just do not commit secrets" is sufficient protection.',
quadrant: 'STRATEGIC',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'STRATEGIC SECURITY PRINCIPLE - Created in response to incident analysis. The breach occurred because only Layer 1 (prevention) and Layer 4 (GitHub scanning) existed. Layers 2, 3, and 5 were missing. This rule requires ALL five layers for security-critical operations. Based on "assume breach" security model where no single control is trusted.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'ADVISORY',
architectural_principle: true,
security_critical: true
}
}
];
console.log('➕ Adding new security rules...\n');
newRules.forEach(rule => {
data.instructions.push(rule);
console.log(` ✓ Added ${rule.id}`);
console.log(` ${rule.text.substring(0, 80)}...`);
console.log('');
});
// Update inst_054 to mark as superseded
const inst_054 = data.instructions.find(i => i.id === 'inst_054');
if (inst_054) {
if (!inst_054.notes.includes('Superseded')) {
inst_054.notes += '\n\nSuperseded by inst_071 on 2025-10-21 which adds secret detection and credential audit steps.';
}
inst_054.active = false;
console.log(' ⊝ Deprecated inst_054 (superseded by inst_071)\n');
}
// Update version and stats
data.version = '3.7';
data.last_updated = new Date().toISOString();
const activeInstructions = data.instructions.filter(i => i.active !== false);
const quadrantCounts = {
SYSTEM: 0,
STRATEGIC: 0,
OPERATIONAL: 0,
TACTICAL: 0
};
const persistenceCounts = {
HIGH: 0,
MEDIUM: 0,
LOW: 0
};
activeInstructions.forEach(inst => {
if (inst.quadrant) quadrantCounts[inst.quadrant]++;
if (inst.persistence) persistenceCounts[inst.persistence]++;
});
data.stats = {
total_instructions: data.instructions.length,
active_instructions: activeInstructions.length,
by_quadrant: quadrantCounts,
by_persistence: persistenceCounts
};
console.log('📊 Updating version and stats...');
console.log(` Version: 3.6 → 3.7`);
console.log(` Total: ${data.instructions.length}`);
console.log(` Active: ${data.stats.active_instructions}\n`);
// Write updated file
fs.writeFileSync(INSTRUCTION_FILE, JSON.stringify(data, null, 2));
console.log(`💾 Written to ${path.basename(INSTRUCTION_FILE)}\n`);
console.log('═══════════════════════════════════════════════════════════');
console.log(' ✅ SECURITY RULES ADDED SUCCESSFULLY');
console.log('═══════════════════════════════════════════════════════════');
console.log('');
console.log('New rules:');
console.log(' inst_069: Credential Handling in Documentation');
console.log(' inst_070: Pre-Commit Secret Detection');
console.log(' inst_071: Enhanced Pre-Deployment Checklist');
console.log(' inst_072: Assume Breach - Defense in Depth');
console.log('');
console.log('Next steps:');
console.log(' 1. Sync to MongoDB: node scripts/sync-instructions-to-db.js');
console.log(' 2. Run credential scan: rg -i "sk-" --hidden');
console.log(' 3. Install gitleaks: brew install gitleaks (or apt/yum)');
console.log(' 4. Create pre-commit hook: scripts/install-gitleaks-hook.sh');
console.log('');

500
scripts/apply-governance-audit-2025-10-21.js
View file

@ -1,500 +0,0 @@
#!/usr/bin/env node
/**
* Apply Governance Audit Recommendations (2025-10-21)
*
* This script implements the recommendations from GOVERNANCE_RULES_AUDIT_2025-10-21.md:
* - Consolidates 12 overlapping rules into 4 consolidated rules
* - Creates 5 new rules to fill coverage gaps
* - Splits inst_024 into 5 granular rules
* - Adjusts persistence levels and quadrant classifications
* - Updates version from 3.5 to 3.6
*/
const fs = require('fs');
const path = require('path');
const INSTRUCTION_FILE = path.join(__dirname, '../.claude/instruction-history.json');
console.log('═══════════════════════════════════════════════════════════');
console.log(' GOVERNANCE AUDIT IMPLEMENTATION - 2025-10-21');
console.log('═══════════════════════════════════════════════════════════\n');
// Read current data
console.log('📖 Reading current instruction-history.json...');
const data = JSON.parse(fs.readFileSync(INSTRUCTION_FILE, 'utf8'));
console.log(` Version: ${data.version}`);
console.log(` Instructions: ${data.instructions.length}`);
console.log(` Active: ${data.instructions.filter(i => i.active !== false).length}\n`);
// Step 1: Deprecate rules that will be consolidated or replaced
console.log('🗑️ Step 1: Deprecating rules...');
const deprecations = [
// Consolidated into inst_008_CONSOLIDATED
{ id: 'inst_008', reason: 'Consolidated into inst_008_CONSOLIDATED (CSP and security headers)' },
{ id: 'inst_044', reason: 'Consolidated into inst_008_CONSOLIDATED (CSP and security headers)' },
{ id: 'inst_048', reason: 'Consolidated into inst_008_CONSOLIDATED (CSP and security headers)' },
// Consolidated into inst_020_CONSOLIDATED
{ id: 'inst_020', reason: 'Consolidated into inst_020_CONSOLIDATED (deployment permissions)' },
{ id: 'inst_022', reason: 'Consolidated into inst_020_CONSOLIDATED (deployment permissions)' },
// Consolidated into inst_041_CONSOLIDATED
{ id: 'inst_041', reason: 'Consolidated into inst_041_CONSOLIDATED (file input validation)' },
{ id: 'inst_042', reason: 'Consolidated into inst_041_CONSOLIDATED (file input validation)' },
// Consolidated into inst_063_CONSOLIDATED
{ id: 'inst_028', reason: 'Consolidated into inst_063_CONSOLIDATED (public GitHub management)' },
{ id: 'inst_062', reason: 'Consolidated into inst_063_CONSOLIDATED (public GitHub management)' },
{ id: 'inst_063', reason: 'Consolidated into inst_063_CONSOLIDATED (public GitHub management)' },
// Replaced by inst_064
{ id: 'inst_007', reason: 'Replaced by inst_064 (framework component usage - more specific)' },
// Split into inst_024a/b/c/d/e
{ id: 'inst_024', reason: 'Split into inst_024a/b/c/d/e for granular enforcement' }
];
deprecations.forEach(({ id, reason }) => {
const rule = data.instructions.find(i => i.id === id);
if (rule) {
rule.active = false;
rule.deprecation_reason = reason;
rule.deprecated_date = '2025-10-21';
rule.deprecated_session = '2025-10-07-001';
console.log(` ✓ Deprecated ${id}`);
} else {
console.log(` ✗ WARNING: ${id} not found`);
}
});
console.log('');
// Step 2: Add consolidated rules
console.log('➕ Step 2: Adding consolidated rules...');
const consolidatedRules = [
{
id: 'inst_008_CONSOLIDATED',
text: 'ALL HTML/JS must comply with Content Security Policy: no inline event handlers (onclick, onload, etc.), no inline scripts, no inline styles. ALL HTTP responses MUST include comprehensive security headers: Content-Security-Policy, Strict-Transport-Security, X-Frame-Options (DENY), X-Content-Type-Options (nosniff), Referrer-Policy (strict-origin-when-cross-origin). Pre-tool execution hook validators (validate-file-write.js, validate-file-edit.js) MUST check CSP compliance before allowing edits and provide specific violation details if blocked.',
quadrant: 'SYSTEM',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CONSOLIDATED from inst_008, inst_044, inst_048. Single source of truth for CSP and security header requirements. Prevents CSP violations and security header omissions.',
deprecates: ['inst_008', 'inst_044', 'inst_048'],
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
enforcement_location: 'pre-tool-hooks'
}
},
{
id: 'inst_020_CONSOLIDATED',
text: 'Web application deployments MUST ensure correct file permissions before going live. Public-facing HTML/CSS/JS: 644 (rw-r--r--), executable scripts: 755 (rwxr-xr-x), admin directories: 750 (rwxr-x---). ALL deployment scripts (rsync, scp, git pull) MUST include automated post-deployment permission correction commands. Verify with "ls -la" before declaring deployment complete. Permission errors are recurring deployment failures - automated correction is mandatory.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CONSOLIDATED from inst_020, inst_022. Prevents public access to admin directories and execution of static files. Recurring issue required automation mandate.',
deprecates: ['inst_020', 'inst_022'],
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
automation_required: true
}
},
{
id: 'inst_041_CONSOLIDATED',
text: 'ALL file inputs (web uploads, email attachments, user-provided files) MUST be validated before processing: (1) File type whitelist validation (reject executables, scripts), (2) Size limits enforced, (3) Content scanning for malware/XSS payloads, (4) Secure storage (GridFS with encryption), (5) Access control (authenticated users only, role-based permissions). Reject and log all suspicious files per inst_046 (security event logging). Never trust client-provided MIME types - verify file signatures.',
quadrant: 'SYSTEM',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CONSOLIDATED from inst_041, inst_042. Comprehensive file/attachment security validation. Part of security vetting framework.',
deprecates: ['inst_041', 'inst_042'],
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
security_critical: true
}
},
{
id: 'inst_063_CONSOLIDATED',
text: 'Public GitHub repository (tractatus-framework) must remain implementation-focused. Prohibited without explicit approval: (1) Governance research documents, (2) Pluralistic deliberation guides, (3) Theoretical frameworks, (4) Project-specific internal documentation, (5) Business strategy documents. Allowed: (1) Technical implementation documentation, (2) API reference guides, (3) Code examples and tutorials, (4) Installation/setup guides, (5) Contribution guidelines. README.md must be reviewed weekly and "Last Updated" date updated when material changes occur. README is primary external interface - must be world-class and current.',
quadrant: 'STRATEGIC',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CONSOLIDATED from inst_028, inst_062, inst_063. Created after bad actor incident where AI converted implementation docs to authoritarian governance guide. Prevents misrepresentation of framework purpose.',
deprecates: ['inst_028', 'inst_062', 'inst_063'],
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'ADVISORY',
requires_user_approval: true,
review_frequency: 'weekly'
}
}
];
consolidatedRules.forEach(rule => {
data.instructions.push(rule);
console.log(` ✓ Added ${rule.id}`);
});
console.log('');
// Step 3: Add new rules (coverage gaps)
console.log('➕ Step 3: Adding new rules (coverage gaps)...');
const newRules = [
{
id: 'inst_064',
text: 'Tractatus framework components MUST be actively used throughout sessions: (1) ContextPressureMonitor: At session start (baseline), 50k/100k/150k token milestones, after complex multi-file operations, after errors. (2) InstructionPersistenceClassifier: When user gives explicit instruction, configuration specifications, architectural constraints. (3) CrossReferenceValidator: Before database schema changes, configuration modifications, architectural decisions. (4) BoundaryEnforcer: Before privacy policy decisions, ethical trade-offs, values-sensitive content. (5) MetacognitiveVerifier: For operations with 3+ file modifications or 5+ sequential steps. (6) PluralisticDeliberationOrchestrator: When BoundaryEnforcer flags values conflict. Framework fade (components not being used) = CRITICAL FAILURE. Update .claude/session-state.json after each component use with timestamp and validation count.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'CRITICAL ENFORCEMENT GAP - Previously documented but not enforced as rule. Specifies exactly when each component must be used. Replaces vague inst_007.',
replaces: ['inst_007'],
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
framework_critical: true,
failure_mode: 'CRITICAL'
}
},
{
id: 'inst_065',
text: 'MANDATORY at session start and immediately after conversation compaction: Run "node scripts/session-init.js", then report to user: (1) Server status: curl -s http://localhost:9000/health | jq -r \'.status\' (expect \'ok\'), (2) Framework statistics: session ID, active instructions count, version from .claude/session-state.json and .claude/instruction-history.json, (3) MongoDB status: active rules count from tractatus_dev database. BLOCK all session work until initialization complete and results reported to user. Output results in clean formatted summary before proceeding with any tasks.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Required by CLAUDE.md but not previously enforced as rule. Ensures framework operational before work begins. Critical for session continuity after compaction.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
triggers: ['session_start', 'post_compaction']
}
},
{
id: 'inst_066',
text: 'ALL git commits MUST use conventional commit format: "type(scope): description". Types: feat (new feature), fix (bug fix), docs (documentation), refactor (code restructure), test (test additions), chore (maintenance). Include Claude Code attribution footer:\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\nCo-Authored-By: Claude <noreply@anthropic.com>\n\nNEVER use "git commit -i" or "git add -i" (interactive modes not supported). When pre-commit hooks modify files, verify commit authorship (git log -1 --format=\'%an %ae\') before amending - NEVER amend other developers\' commits.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Documented in Maintenance Guide but not enforced as rule. Improves git history quality and provides attribution transparency.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'ADVISORY',
quality_standard: true
}
},
{
id: 'inst_067',
text: 'BEFORE database operations or port-specific commands: (1) VERIFY current environment (local vs production) from context, (2) VERIFY correct port/database from explicit user instruction OR CLAUDE.md defaults (local: tractatus_dev:27017 on port 9000, production: tractatus_prod:27017 on port 9000), (3) If user specifies non-standard port or database (e.g., port 27027, custom database name), USE EXACT VALUE FROM USER INSTRUCTION - do NOT autocorrect to standard defaults. Pattern recognition bias for standard ports/databases is a known 27027 failure mode where training data associations override explicit instructions. When in doubt, ask user to confirm environment.',
quadrant: 'SYSTEM',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Prevents 27027-type failures where pattern recognition overrides explicit user instructions. Critical for multi-environment operations.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
failure_prevention: '27027_pattern_bias',
blocking: true
}
},
{
id: 'inst_068',
text: 'Run tests in these scenarios: (1) Before git commits if tests exist for modified code area, (2) Before all deployments (run full test suite), (3) After refactoring (run affected tests), (4) When user explicitly requests testing. Test failures BLOCK commits and deployments unless user explicitly approves proceeding with failing tests. When creating new features, ask user if tests should be written - do not assume test requirements. Report test results with counts: X passed, Y failed, Z skipped. Use "npm test" for full suite or "npm test -- <path>" for specific tests.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Aligns with world-class quality standard (inst_004). Prevents regressions and maintains code quality.',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
blocking: true,
quality_critical: true
}
}
];
newRules.forEach(rule => {
data.instructions.push(rule);
console.log(` ✓ Added ${rule.id}`);
});
console.log('');
// Step 4: Add split rules (inst_024a-e)
console.log('➕ Step 4: Adding split rules (inst_024a-e)...');
const splitRules = [
{
id: 'inst_024a',
text: 'Before session handoff or closedown: Kill all background processes spawned during session (npm, jest, node, dev servers, file watchers). Use "ps aux | grep -E \\"npm|jest|node\\"" to find processes, "pkill -f <pattern>" to terminate. Verify cleanup with "ps aux | grep -E \\"npm|jest|node\\"" again (should show no results except grep itself). Update .claude/session-state.json with cleanup timestamp and process count terminated.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Split from inst_024 for granular enforcement. Part of comprehensive closedown protocol.',
part_of: 'inst_024_series',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
closedown_step: 1
}
},
{
id: 'inst_024b',
text: 'Before session handoff: Verify .claude/instruction-history.json changes are synced to MongoDB governanceRules collection. If instruction-history.json modified this session, run "node scripts/sync-instructions-to-db.js" to sync. Compare counts: active instructions in JSON vs active rules in database. Report sync status in handoff document: "Synced: X instructions → Y database rules" or "Not needed: No changes this session".',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Split from inst_024 for granular enforcement. Ensures file-database consistency.',
part_of: 'inst_024_series',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
closedown_step: 2
}
},
{
id: 'inst_024c',
text: 'Before session handoff: Document complete git status: (1) Current branch, (2) Commits ahead/behind remote (git status shows "Your branch is ahead of origin/main by X commits"), (3) Working tree status (clean vs untracked files), (4) Most recent commits (git log --oneline -5). Include in handoff document with explanations for any untracked files (e.g., "untracked files are INTERNAL project files, NOT for public repo"). If working tree has uncommitted changes, explain why or commit before handoff.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Split from inst_024 for granular enforcement. Provides next session with clear git context.',
part_of: 'inst_024_series',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
closedown_step: 3
}
},
{
id: 'inst_024d',
text: 'Before session handoff: Clean temporary artifacts created during session: (1) .memory-test/ directory (if exists from testing), (2) Test databases (mongosh --eval "db.dropDatabase()" on tractatus_test), (3) Stale lock files (check age - if hours old with no process, safe to delete), (4) Temporary scripts in /tmp/. Document what was cleaned and what was intentionally kept (e.g., "package-lock.json kept - legitimate", "mongod.lock kept - server running"). Do NOT delete legitimate lock files for running processes.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Split from inst_024 for granular enforcement. Prevents clutter accumulation across sessions.',
part_of: 'inst_024_series',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'ADVISORY',
closedown_step: 4
}
},
{
id: 'inst_024e',
text: 'Create session handoff document as OPTIMAL_STARTUP_PROMPT_<DATE>.md with: (1) Current system status (server, framework, database, git), (2) Completed tasks with file:line references and verification, (3) In-progress tasks with blockers and next steps, (4) Pending tasks prioritized by user importance, (5) Recent instruction additions/changes with rationale, (6) Known issues and gotchas, (7) Framework health assessment, (8) User decisions needed, (9) Ready-to-use TodoWrite JSON for next session, (10) Recommended startup sequence with exact commands. STOP ALL WORK IMMEDIATELY after creating handoff document - handoff signals NEW session intent, not continuation.',
quadrant: 'OPERATIONAL',
persistence: 'HIGH',
temporal_scope: 'PERMANENT',
session_id: '2025-10-07-001',
notes: 'Split from inst_024 for granular enforcement. Core handoff creation with strict format requirements.',
part_of: 'inst_024_series',
active: true,
created_date: '2025-10-21',
parameters: {
verification_required: 'MANDATORY',
closedown_step: 5,
terminal_action: true
}
}
];
splitRules.forEach(rule => {
data.instructions.push(rule);
console.log(` ✓ Added ${rule.id}`);
});
console.log('');
// Step 5: Adjust persistence levels and quadrant classifications
console.log('🔧 Step 5: Adjusting persistence and quadrants...');
const adjustments = [
{ id: 'inst_011', changes: { persistence: 'MEDIUM' }, reason: 'Lowered from HIGH - implementation detail' },
{ id: 'inst_021', changes: { persistence: 'MEDIUM', quadrant: 'TACTICAL' }, reason: 'Lowered from HIGH, reclassified to TACTICAL' },
{ id: 'inst_059', changes: { quadrant: 'TACTICAL' }, reason: 'Reclassified from OPERATIONAL to TACTICAL' },
{ id: 'inst_061', changes: { quadrant: 'TACTICAL' }, reason: 'Reclassified from OPERATIONAL to TACTICAL' },
];
adjustments.forEach(({ id, changes, reason }) => {
const rule = data.instructions.find(i => i.id === id);
if (rule) {
Object.assign(rule, changes);
if (!rule.adjustment_history) rule.adjustment_history = [];
rule.adjustment_history.push({
date: '2025-10-21',
session: '2025-10-07-001',
changes,
reason
});
console.log(` ✓ Adjusted ${id}: ${reason}`);
} else {
console.log(` ✗ WARNING: ${id} not found`);
}
});
console.log('');
// Step 6: Update inst_009 text (Stripe status)
console.log('🔧 Step 6: Updating inst_009 text...');
const inst_009 = data.instructions.find(i => i.id === 'inst_009');
if (inst_009) {
inst_009.text = 'Stripe payment processing is ACTIVE (test keys configured). Email services (verification emails, donation receipts) are deferred until production launch. ProtonBridge email integration is Phase 2+.';
inst_009.notes = 'Updated 2025-10-21: Stripe fully implemented and active (test keys configured). Email services remain deferred until production launch with ProtonBridge integration planned for Phase 2+.';
console.log(' ✓ Updated inst_009 text and notes');
} else {
console.log(' ✗ WARNING: inst_009 not found');
}
console.log('');
// Step 7: Enhance vague rules
console.log('🔧 Step 7: Enhancing vague rules...');
const inst_040 = data.instructions.find(i => i.id === 'inst_040');
if (inst_040) {
inst_040.text = 'When user says "all" (e.g., "update all pages", "fix all instances", "check all files"), Claude MUST: (1) Use Glob/Grep to find ALL matches, (2) List every item found with file:line references, (3) Confirm with user before proceeding, (4) Track completion of each item. NEVER assume "all" means "a few examples" or "the ones I found first".';
console.log(' ✓ Enhanced inst_040 with specific examples');
} else {
console.log(' ✗ WARNING: inst_040 not found');
}
const inst_047 = data.instructions.find(i => i.id === 'inst_047');
if (inst_047) {
inst_047.text = 'NEVER dismiss, downplay, or avoid user requests by claiming "too hard", "too complex", "beyond capabilities". When facing difficult requests: (1) Acknowledge complexity honestly, (2) Break into smaller steps, (3) Identify blockers explicitly, (4) Propose alternative approaches, (5) Ask user for priorities/trade-offs. If truly impossible, explain technical limitations with evidence, not vague dismissal.';
console.log(' ✓ Enhanced inst_047 with positive guidance');
} else {
console.log(' ✗ WARNING: inst_047 not found');
}
const inst_054 = data.instructions.find(i => i.id === 'inst_054');
if (inst_054) {
inst_054.text = 'PRE-DEPLOYMENT CHECKLIST (run in order):\n□ 1. CSP Compliance Check [AUTOMATED via hook]\n□ 2. Local Server Test (curl http://localhost:9000/health → 200 OK)\n□ 3. Comprehensive Testing (npm test → all pass)\n□ 4. Permission Verification (ls -la → correct 644/755)\n□ 5. Git Status Clean (no uncommitted changes)\nMark each checkbox before proceeding to next. BLOCK deployment if any step fails.';
console.log(' ✓ Enhanced inst_054 with checklist format');
} else {
console.log(' ✗ WARNING: inst_054 not found');
}
console.log('');
// Step 8: Update version and recalculate stats
console.log('📊 Step 8: Updating version and recalculating stats...');
data.version = '3.6';
data.last_updated = new Date().toISOString();
// Recalculate stats
const activeInstructions = data.instructions.filter(i => i.active !== false);
const quadrantCounts = {
SYSTEM: 0,
STRATEGIC: 0,
OPERATIONAL: 0,
TACTICAL: 0
};
const persistenceCounts = {
HIGH: 0,
MEDIUM: 0,
LOW: 0
};
activeInstructions.forEach(inst => {
if (inst.quadrant) quadrantCounts[inst.quadrant]++;
if (inst.persistence) persistenceCounts[inst.persistence]++;
});
data.stats = {
total_instructions: data.instructions.length,
active_instructions: activeInstructions.length,
by_quadrant: quadrantCounts,
by_persistence: persistenceCounts
};
console.log(' ✓ Updated to version 3.6');
console.log(` ✓ Stats: ${data.stats.active_instructions} active / ${data.stats.total_instructions} total`);
console.log('');
// Step 9: Write updated file
console.log('💾 Step 9: Writing updated instruction-history.json...');
// Create backup first
const backupFile = INSTRUCTION_FILE + '.backup-3.5-' + Date.now();
fs.copyFileSync(INSTRUCTION_FILE, backupFile);
console.log(` ✓ Backup created: ${path.basename(backupFile)}`);
fs.writeFileSync(INSTRUCTION_FILE, JSON.stringify(data, null, 2));
console.log(` ✓ Written to ${path.basename(INSTRUCTION_FILE)}`);
console.log('');
// Summary
console.log('═══════════════════════════════════════════════════════════');
console.log(' SUMMARY');
console.log('═══════════════════════════════════════════════════════════\n');
console.log('📊 CHANGES:');
console.log(` Version: 3.5 → 3.6`);
console.log(` Total instructions: 54 → ${data.stats.total_instructions}`);
console.log(` Active instructions: 54 → ${data.stats.active_instructions}`);
console.log(` Deprecated: ${deprecations.length} rules`);
console.log(` Added consolidated: ${consolidatedRules.length} rules`);
console.log(` Added new: ${newRules.length} rules`);
console.log(` Added split: ${splitRules.length} rules`);
console.log(` Adjusted: ${adjustments.length} rules`);
console.log(` Enhanced: 3 rules`);
console.log('');
console.log('📋 BY QUADRANT:');
Object.entries(data.stats.by_quadrant).forEach(([q, count]) => {
console.log(` ${q}: ${count}`);
});
console.log('');
console.log('🔒 BY PERSISTENCE:');
Object.entries(data.stats.by_persistence).forEach(([p, count]) => {
console.log(` ${p}: ${count}`);
});
console.log('');
console.log('✅ Governance audit implementation COMPLETE');
console.log('');
console.log('NEXT STEPS:');
console.log('1. Sync to MongoDB: node scripts/sync-instructions-to-db.js');
console.log('2. Run framework tests: npm test');
console.log('3. Verify session initialization: node scripts/session-init.js');
console.log('');