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

```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

---

## 🎯 QUICK REFERENCE

**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)
**Approval required**: Architectural changes, DB schema, security, values
**Quality**: World-class, no shortcuts, no fake data

**Common Commands**:
```bash
# Session management
node scripts/session-init.js                  # Initialize session (MANDATORY)
node scripts/session-closedown.js             # End session (user request only)
node scripts/check-session-pressure.js        # Check context pressure

# Local development
npm start                                     # Start local server (port 9000)

# 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

# Service management (remote)
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"

# 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

- **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-10-25 (Added unified deployment script; cache versioning now auto-committed)
**Philosophy**: If it can be enforced in code, it should not be documented here.