tractatus/CLAUDE.md

# Tractatus - Quick Reference

## 🚨 CRITICAL - DO NOT SKIP

**FIRST ACTION EVERY SESSION (including post-compaction):**
```bash
node scripts/session-init.js
```
**BLOCKS if**: Local server not running on port 9000 → Fix: `npm start` in new terminal

**Framework Triggers**: `ff` = framework audit | `ffs` = framework stats

**Session End** (user request only): `node scripts/session-closedown.js` → STOP ALL WORK after completion

---

## ⚡ Quick Commands

**Session Management:**
```bash
node scripts/session-init.js                  # Initialize (MANDATORY - blocks without port 9000)
node scripts/session-closedown.js             # End session (user request only)
node scripts/framework-stats.js --tokens=X/200000  # Framework status
node scripts/check-session-pressure.js        # Context pressure check
```

**Development:**
```bash
npm start                                     # Start local server (port 9000 - REQUIRED)
./scripts/deploy.sh                           # Deploy to production
./scripts/deploy.sh --dry-run                 # Preview deployment
```

**Remote Service:**
```bash
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"
```

**Environment:**
- **Database**: tractatus_dev (MongoDB port 27017)
- **App**: Node.js/Express on port 9000 (systemd, NOT pm2)
- **Stack**: Vanilla JS, Tailwind CSS, MongoDB
- **Separate from**: family-history, sydigital (no shared code)
- **Quality**: World-class, no shortcuts, no fake data
- **Approval required**: Architectural changes, DB schema, security, values

---

## 📖 Full Documentation

### ⚠️ MANDATORY SESSION START

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

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

This script enforces:
- ✅ Local development server running on port 9000 (BLOCKS if not running)
- ✅ Framework components initialized and operational
- ✅ Token checkpoints configured (50k, 100k, 150k)
- ✅ Session state tracking active
- ✅ Instruction history loaded

**If blocked**: Follow on-screen instructions to start local server, then re-run.

---

### ⚠️ SESSION CLOSEDOWN

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

**Run when user requests**: "wrap up", "end session", "create handoff", "process session closedown"

This script executes:
- ✅ Background process cleanup
- ✅ Instruction database sync verification
- ✅ Framework performance analysis (all 6 services)
- ✅ Audit log analysis with rule suggestions
- ✅ Git status documentation
- ✅ Comprehensive handoff document creation
- ✅ Compaction marker for next session detection

**STOP ALL WORK** after script completes. Script output includes next session startup instructions.

---

### 🔍 FRAMEWORK TRIGGER: "ff"

When user prefixes prompt with **ff**, invoke full framework audit:

```bash
node scripts/framework-audit-response.js \
  --prompt "user's actual question" \
  --type "boundary_question"
```

**Purpose**: Manually trigger ALL 6 framework services for conversational responses (BoundaryEnforcer, PluralisticDeliberationOrchestrator, MetacognitiveVerifier, CrossReferenceValidator, ContextPressureMonitor, InstructionPersistenceClassifier).

**When**: User asks questions about VALUES, trade-offs, architectural decisions, or boundary-crossing topics.

**Output**: Include audit IDs in response (e.g., "🔍 Framework Audit: audit_67abc123")

**See**: inst_078 in instruction-history.json

### 🔍 FRAMEWORK TRIGGER: "ffs"

When user types **ffs**, display full framework statistics:

```bash
# With real-time context pressure (recommended)
node scripts/framework-stats.js --tokens=<current>/<budget>

# With cached data (may be stale)
node scripts/framework-stats.js
```

**Purpose**: On-demand visibility into framework operational metrics during session

**Reports**:
- Session state (ID, message count, status)
- Token usage & checkpoints (25%, 50%, 75%)
- Context pressure level & metrics (real-time when --tokens provided)
- Instruction counts (by quadrant/persistence)
- Audit log counts (by service)
- Framework service status (all 6 services)

**Output**: Formatted report + JSON for programmatic access

**Important**: Use `--tokens=` parameter for accurate real-time pressure. Without it, displays cached session data which may show 0% pressure.

**When**: User wants to see framework health/activity at any point in session

**See**: inst_082 in instruction-history.json

---

### 📋 Common Commands Reference

```bash
# Production deployment (unified workflow)
./scripts/deploy.sh                           # Full deployment (auto-detects changes, auto-commits cache)
./scripts/deploy.sh --frontend-only           # Frontend-only (public/ directory)
./scripts/deploy.sh --force-cache --restart   # Force cache update + restart service
./scripts/deploy.sh --dry-run                 # Preview without deploying

# Document workflow
npm run migrate:docs -- --source docs/markdown --force
node scripts/generate-single-pdf.js <input.md> <output.pdf>
```

---

## 🚨 FRAMEWORK ENFORCEMENT

**Governance is ENFORCED architecturally, not documented:**

1. **session-init.js** - Blocks without local server on port 9000
2. **Framework components** - Initialize automatically, run continuously
3. **Token checkpoints** - Report pressure at 50k, 100k, 150k
4. **Pre-action checks** - `node scripts/pre-action-check.js <type> [path] "<desc>"`

**Framework fade** = enforcement gap → fix architecturally, not in docs.

---

## 📚 REFERENCE DOCUMENTS

- **docs/SESSION_MANAGEMENT_REFERENCE.md** - Session workflow guide, checklists, troubleshooting
- **CLAUDE_Tractatus_Maintenance_Guide.md** - Full governance framework
- **docs/SESSION_MANAGEMENT_ARCHITECTURE.md** - Session lifecycle design
- **.claude/instruction-history.json** - Persistent instruction database (auto-accessed)

---

**Last Updated**: 2025-11-24 (Optimized session management documentation; added Quick Reference)
**Philosophy**: If it can be enforced in code, it should not be documented here.