tractatus/NEW_SESSION_STARTUP_PROMPT_2025-10-19.md

New Session Startup Prompt - Tractatus Framework

Date: 2025-10-19 Purpose: Initialize NEW Claude Code session for Tractatus project Previous Session: Document security overhaul (completed successfully)

---

📋 Copy-Paste Startup Prompt

I'm starting a new Claude Code session for the Tractatus project. Here's the current state:

PROJECT CONTEXT:
- Tractatus Framework: Agentic governance system for LLM applications
- Tech stack: Node.js/Express backend, MongoDB database, vanilla JS frontend, Tailwind CSS
- Local dev: http://localhost:9000, Database: tractatus_dev (port 27017)
- Production: https://agenticgovernance.digital (systemd service: tractatus.service)
- Separate from family-history and sydigital projects (no shared code)

RECENT MAJOR WORK (2025-10-19):
✅ Completed comprehensive document security overhaul:
  - Implemented publish workflow (documents default to 'internal', require explicit admin publish)
  - Fixed security breach: deleted 71 internal documents exposed via search
  - Generated 6 missing PDFs for public documents
  - Fixed mobile navigation UX issues
  - Optimized pedagogical ordering for 34 public documents
  - All changes deployed to production and verified

CURRENT STATE:
- 34 public documents (27 public + 7 archived)
- Zero internal documents exposed via public API
- Publish workflow active: POST /api/documents/:id/publish (admin only)
- All documents have downloadable PDFs
- Mobile-responsive documentation viewer working correctly
- Production verified stable and secure

QUALITY STANDARDS:
- World-class quality (no shortcuts, no fake data)
- User approval required for: architectural changes, DB schema, security, values content
- Always use pre-action checks: node scripts/pre-action-check.js <type> [path] "<desc>"
- Development server MUST be running on port 9000 (session-init.js enforces this)

IMMEDIATE NEXT STEPS:
Please run the mandatory session initialization:
```bash
node scripts/session-init.js

After initialization completes, I'll be ready to work on:

• [Specify your current priority or ask me for recommendations]

See CLAUDE.md and SESSION_HANDOFF_2025-10-19_DOCUMENT_SECURITY.md for full context.

---

## 🎯 Why This Prompt?

### 1. **Essential Context Without Overwhelming**
- Provides just enough context to understand the project
- References handoff document for deep dive
- Focuses on recent work (most relevant for continuity)

### 2. **Current State Clarity**
- Lists concrete numbers (34 documents, 0 exposed)
- Mentions recent security changes
- Confirms production stability

### 3. **Quality Standards Reminder**
- World-class quality requirement
- Approval gates for critical changes
- Pre-action checks (architectural enforcement)

### 4. **Actionable Start**
- Clear first command: `node scripts/session-init.js`
- Placeholder for user's immediate priority
- References to full documentation

---

## 📚 Reference Documents

The new session should have quick access to:

1. **CLAUDE.md** - Project-level governance and conventions
2. **SESSION_HANDOFF_2025-10-19_DOCUMENT_SECURITY.md** - Detailed previous session summary
3. **DOCUMENT_SECURITY_IMPROVEMENTS.md** - Technical specification of security changes
4. **CLAUDE_Tractatus_Maintenance_Guide.md** - Full maintenance and operational guide
5. **PRE_APPROVED_COMMANDS.md** - Pre-approved bash command patterns

---

## 🔍 Common First Tasks

Based on project patterns, new sessions often start with:

### Development Tasks
- Feature implementation (blog, pluralistic deliberation, API enhancements)
- Bug fixes (UI issues, mobile responsiveness, accessibility)
- Performance optimization (caching, bundle size, database queries)
- Documentation updates (content refresh, new features)

### Deployment Tasks
- Production deployment verification
- Database migrations
- Environment configuration
- Service monitoring

### Content Tasks
- Document creation/editing
- PDF generation
- Translation updates
- Content categorization

### Infrastructure Tasks
- Security audits
- Dependency updates
- Testing coverage
- CI/CD improvements

---

## ⚠️ Common Pitfalls to Avoid

### 1. **Forgetting Session Init**
**Problem:** Framework fade without proper initialization
**Solution:** Always run `node scripts/session-init.js` FIRST

### 2. **Working Without Local Server**
**Problem:** Cannot test changes, deployment fails
**Solution:** session-init.js enforces local server on port 9000

### 3. **Skipping Pre-Action Checks**
**Problem:** Violate architectural constraints, CSP violations
**Solution:** Use `node scripts/pre-action-check.js` before file edits/writes

### 4. **Assuming Shared Code**
**Problem:** Mixing Tractatus with family-history or sydigital
**Solution:** Completely separate codebases (no shared utilities)

### 5. **Deploying Without Verification**
**Problem:** Breaking production
**Solution:** Always verify locally first, use safe deployment script

---

## 🚀 Recommended Focus Areas

Based on project roadmap and recent work:

### High Priority
1. **Admin UI for Publish Workflow** - Currently API-only, needs user interface
2. **CSP Violation Cleanup** - 114 violations in 17 files (deferred from security work)
3. **Pluralistic Deliberation Feature** - Core framework capability (in progress)
4. **Blog System Polish** - Recently implemented, needs refinement

### Medium Priority
1. **Document Migration to `visibility` Field** - Remove legacy `public` field
2. **Workflow Status UI** - Show draft/review/published states in admin
3. **Performance Optimization** - Lighthouse scores, bundle size
4. **Accessibility Audit** - WCAG compliance, screen reader testing

### Low Priority
1. **Translation Updates** - German/French content refresh
2. **Analytics Integration** - Usage tracking, document popularity
3. **Search Enhancement** - Better relevance, faceted filtering
4. **API Documentation** - OpenAPI/Swagger generation

---

## 🔐 Security Awareness

### Recent Security Changes (Critical Context)
The previous session discovered and fixed a major security breach. Be aware:

1. **Documents Now Default to Internal** - This is intentional and must be preserved
2. **Publish Workflow Required** - No document becomes public without explicit admin action
3. **Category Validation** - Public documents MUST have valid category (not "none")
4. **Audit Trail** - All publish/unpublish actions tracked with who/when/why

### Security Checklist for New Work
- [ ] Does this change affect document visibility?
- [ ] Could this expose internal documents?
- [ ] Does this bypass publish workflow?
- [ ] Are validation rules still enforced?
- [ ] Is audit trail maintained?

---

## 📊 Key Metrics to Monitor

### Document Health
- Public documents: **27** (expected)
- Archived documents: **7** (expected)
- Internal documents: **0 exposed** (critical)
- Draft documents: Should remain low (efficient workflow)

### System Health
- Local dev server: **port 9000** (must be running)
- Production server: **systemd tractatus.service** (should be active)
- Database: **MongoDB port 27017** (should be connected)
- Framework components: **6 active** (session-init.js reports)

### Quality Metrics
- Lighthouse performance: Target **>90**
- CSP violations: **114** (known issue, separate cleanup)
- Test coverage: Monitor with `npm test`
- Build success: Monitor with `npm run build`

---

## 🎓 Session Init Expectations

When you run `node scripts/session-init.js`, expect:

### ✅ Success Output

══════════════════════════════════════════════════════════════════════ Tractatus Framework - Session Initialization ══════════════════════════════════════════════════════════════════════

▶ 1. Checking Session Status Session: NEW Messages: 1

▶ 2. Resetting Token Checkpoints ✓ Token budget: 200,000 ✓ Next checkpoint: 50,000 tokens (25%)

▶ 3. Loading Instruction History ✓ Active instructions: 39

▶ 4. Running Initial Pressure Check ✓ Pressure Level: NORMAL ✓ Overall Score: 4%

▶ 5. Framework Components ✓ All 6 components: ACTIVE

▶ 6. Development Environment Enforcement ✓ Local development server running on port 9000

══════════════════════════════════════════════════════════════════════ Framework Initialization Complete ══════════════════════════════════════════════════════════════════════

### ❌ Failure Output (Server Not Running)

✗ Local development server is NOT running on port 9000

🚨 SESSION BLOCKED

You must start the development server before proceeding:

npm start

Then re-run this script.

**Action:** Start server with `npm start`, then re-run init.

---

## 🛠️ Quick Reference Commands

### Development
```bash
npm start                                      # Start local server (port 9000)
node scripts/session-init.js                   # MANDATORY session init
node scripts/check-session-pressure.js         # Check context pressure
npm test                                       # Run test suite

Deployment

./scripts/deploy-full-project-SAFE.sh          # Deploy to production (safe)
ssh ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl status tractatus"
ssh 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>
curl https://agenticgovernance.digital/api/documents | jq '.pagination.total'

Database

mongosh tractatus_dev                          # Connect to local DB
mongosh tractatus_prod                         # Connect to production DB (if tunneled)

---

🎯 Session Success Criteria

A successful new session should:

1. ✅ Run session-init.js successfully
2. ✅ Understand current project state (34 documents, security architecture)
3. ✅ Know where to find detailed documentation (handoff, CLAUDE.md)
4. ✅ Be aware of quality standards and approval gates
5. ✅ Have clear next steps or be ready to receive direction
6. ✅ Use pre-action checks before file modifications
7. ✅ Maintain security posture (no regression on document exposure)

---

💡 Tips for Productive Session

Communication

• Ask clarifying questions BEFORE making architectural changes
• Confirm understanding of user requirements
• Provide progress updates for multi-step tasks
• Use TodoWrite for complex workflows

Code Quality

• Follow existing patterns in codebase
• Write world-class code (no shortcuts)
• Test locally before deploying
• Document complex logic

Safety

• Always use pre-action checks
• Never bypass validation for convenience
• Maintain audit trails
• Verify production after deployment

Efficiency

• Run parallel operations when independent
• Use Task tool for complex searches
• Read handoff docs before asking user
• Leverage existing scripts and utilities

---

📞 Getting Unstuck

If you encounter issues:

1. Framework Fade - Re-run node scripts/session-init.js
2. Server Not Running - npm start then re-init
3. Database Connection Failed - Check MongoDB service, verify credentials
4. Deployment Failed - Check logs: ssh ubuntu@vps "sudo journalctl -u tractatus -n 50"
5. Tests Failing - Run npm test -- --verbose for detailed output
6. CSP Violations - Run node scripts/check-csp-violations.js for analysis

---

Last Updated: 2025-10-19 For Session Date: 2025-10-19 or later Session Type: NEW (not continuation) Handoff Document: SESSION_HANDOFF_2025-10-19_DOCUMENT_SECURITY.md