tractatus/CLAUDE.md

# Tractatus - Active Session Governance (Claude Code)

**Project**: Tractatus Website | **Database**: tractatus_dev (port 27017) | **App Port**: 9000
**Status**: Phase 1 Development | **Separate from**: family-history, sydigital

---

## ⚠️ MANDATORY SESSION START PROTOCOL

**IMMEDIATELY upon session start, run ONE command:**

```bash
node scripts/session-init.js
```

**⚠️ CRITICAL: Also run this IMMEDIATELY after continuing from a compacted conversation!**

**This automated script will:**
1. ✅ Detect new session vs. continued session
2. ✅ Initialize session state and reset token checkpoints
3. ✅ Load instruction history (shows active HIGH/MEDIUM/LOW counts)
4. ✅ Run baseline pressure check (ContextPressureMonitor)
5. ✅ Verify all 5 framework components operational
6. ✅ Report framework status to user

**Manual fallback** (if script fails):
- `node scripts/check-session-pressure.js --tokens 0/200000 --messages 0`
- Read `.claude/instruction-history.json` for active instructions

---

## 🔒 FIVE MANDATORY FRAMEWORK COMPONENTS (ALWAYS ACTIVE)

**These MUST be used continuously throughout EVERY session. No exceptions.**

### 1. **ContextPressureMonitor** (Every 25% tokens = 50k)
- **When**: Session start, 50k, 100k, 150k tokens, complex operations, errors
- **Command**: `node scripts/check-session-pressure.js --tokens <current>/<budget> --messages <count>`
- **Update**: `.claude/session-state.json` and `.claude/token-checkpoints.json`

### 2. **InstructionPersistenceClassifier** (All explicit directives)
- **When**: User gives explicit instruction (ports, configs, requirements, constraints)
- **Action**: Classify quadrant (STR/OPS/TAC/SYS/STO), persistence level, temporal scope
- **Store**: Append to `.claude/instruction-history.json`

### 3. **CrossReferenceValidator** (Before major changes)
- **When**: Database changes, config modifications, file edits, architecture decisions
- **Action**: Check `.claude/instruction-history.json` for conflicts
- **Block**: If conflicts with HIGH persistence instructions

### 4. **BoundaryEnforcer** (Before values decisions)
- **When**: Privacy decisions, ethical trade-offs, user agency, mission changes
- **Action**: Verify decision doesn't cross into values territory
- **Block**: All values decisions require human approval

### 5. **MetacognitiveVerifier** (Complex operations only)
- **When**: Operations with >3 files, >5 steps, architecture changes, security implementations
- **Action**: Verify alignment, coherence, completeness, safety, alternatives
- **Report**: Confidence score + alternatives before proceeding

---

## 🚨 FRAMEWORK FADE DETECTION & RECOVERY

**Framework fade = Components not being used. This is CRITICAL FAILURE.**

**Signs of fade:**
- No pressure check in 50k tokens
- No instruction classification when directive given
- No boundary check before values decision
- No validator check before major change

**Immediate action when fade detected:**
1. **STOP all work**
2. **Run**: `node scripts/recover-framework.js`
3. **Report to user**: Framework lapsed, recovery initiated
4. **Resume**: Only after recovery complete

**Automated monitoring**: `npm run dev` now runs framework-watchdog.js in background

---

## 📋 PRE-ACTION CHECK (Required before major actions)

**Before ANY of these, run**: `node scripts/pre-action-check.js <action-type> [file-path] <description>`

Action types: `file-edit`, `database`, `architecture`, `config`, `security`, `values`, `complex`

**File path (optional)**: When editing HTML/JS files, include file path for automated CSP validation
- Example: `node scripts/pre-action-check.js file-edit public/docs.html "Update navigation"`

**Exit codes:**
- 0 = PASS (proceed)
- 1 = FAIL (blocked, address issues)
- 2 = ERROR (system failure)

**🔒 Automated CSP Validation (inst_008 enforcement)**:
- Automatically validates HTML/JS files for Content Security Policy violations
- Detects: inline event handlers (`onclick=`), inline styles (`style=""`), inline scripts, `javascript:` URLs
- Blocks action if violations found - prevents CSP violations from reaching production
- This automated check catches violations that manual review might miss

---

## 📚 DETAILED REFERENCE DOCUMENTS

- **CLAUDE_Tractatus_Maintenance_Guide.md**: Full governance framework, conventions, directory structure
- **docs/claude-code-framework-enforcement.md**: Complete technical documentation
- **.claude/instruction-history.json**: Persistent instruction database
- **.claude/session-state.json**: Current session framework activity
- **.claude/token-checkpoints.json**: Token milestone tracking

---

## 🎯 QUICK REFERENCE

**MongoDB**: Port 27017, database `tractatus_dev`
**Application**: Node.js/Express, port 9000
**Tech Stack**: Vanilla JS, Tailwind CSS, MongoDB, Express
**No shared code**: Separate from family-history and sydigital
**Human approval required**: Architectural changes, DB schema, security, values content
**Quality standard**: World-class, no shortcuts, no fake data

### Process Management: systemd (NOT pm2)

**Production**: `tractatus.service` (systemd service on vps-93a693da.vps.ovh.net)
**Development**: Run via `npm start` (local development) or `tractatus-dev.service` (systemd)

**Key Commands**:
```bash
# Production status/control
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl status tractatus"
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl restart tractatus"
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo journalctl -u tractatus -f"

# Install/update systemd services
./scripts/install-systemd.sh prod  # Production
./scripts/install-systemd.sh dev   # Development (requires sudo password)
```

**Service Files**: `systemd/tractatus-prod.service`, `systemd/tractatus-dev.service`
**Security**: NoNewPrivileges, PrivateTmp, ProtectSystem=strict, 2G memory limit
**Auto-start**: Enabled on boot via `systemctl enable`

---

**Last Updated**: 2025-10-09 (Migrated from pm2 to systemd, added automated CSP validation)
**For full details**: See CLAUDE_Tractatus_Maintenance_Guide.md