tractatus/NEXT_SESSION.md

# Next Session Startup - Tractatus Project

**Last Session:** 2025-10-06
**Project:** Tractatus AI Safety Framework Website
**Status:** Foundation Complete, Ready for Feature Development

---

## Quick Context

You are continuing development of the **Tractatus AI Safety Framework** website platform. This is a **separate project** from family-history and sydigital.

**Key Facts:**
- MongoDB: Port 27017, database `tractatus_dev`
- Application: Port 9000
- Phase: 1 (Local Development)
- Progress: 10/21 tasks complete (47.6%)
- Foundation: ✅ COMPLETE

---

## Immediate Verification Steps

**Run these commands first to verify environment:**

```bash
# 1. Navigate to project
cd /home/theflow/projects/tractatus

# 2. Check MongoDB service
sudo systemctl status mongodb-tractatus
# Expected: active (running)

# 3. Check database
mongosh mongodb://localhost:27017/tractatus_dev --quiet --eval "db.getCollectionNames()"
# Expected: Array of 10 collections

# 4. Check Git status
git status
# Expected: On branch main, working tree clean

# 5. Test server
npm run dev
# Expected: Server starts on port 9000, connects to MongoDB
# Ctrl+C to stop
```

**If any checks fail, see troubleshooting in `SESSION_CLOSEDOWN_20251006.md`**

---

## Project Context Files (READ THESE)

**Essential Reading:**
1. `CLAUDE.md` - Complete project context and conventions
2. `SESSION_CLOSEDOWN_20251006.md` - What was accomplished last session
3. `docs/governance/TRA-VAL-0001-core-values-principles-v1-0.md` - Core values (all decisions align here)

**Reference Documentation:**
- `Tractatus-Website-Complete-Specification-v2.0.md` - Full specification
- `ClaudeWeb conversation transcription.md` - Design discussions
- `README.md` - Project overview

---

## Current State Summary

### ✅ What's Complete (10/21 tasks)

**Infrastructure:**
- MongoDB running (port 27017, 10 collections, 51 indexes)
- Express server foundation (port 9000)
- Systemd service configured
- Git repository (main branch, 5 commits)

**Code:**
- Database utilities (4 files: db, logger, jwt, markdown)
- MongoDB models (7 models with full CRUD)
- Middleware (3 files: auth, validation, error)
- Express server with security (Helmet, CORS, rate limiting)
- Configuration management

**Documentation:**
- CLAUDE.md (project conventions)
- README.md (overview)
- TRA-VAL-0001 (governance)
- SETUP_INSTRUCTIONS.md (terminal commands)

### ⏳ What's Pending (11/21 tasks)

**Immediate Priority:**
1. Core API routes (documents, blog, admin, auth)
2. Document migration pipeline
3. Tractatus governance services (InstructionClassifier, etc.)

**Later:**
4-11. Frontend features (audience paths, demos, AI curation, etc.)

---

## Recommended Next Steps

### Option A: Build Core API Routes (Recommended)

**Start here:**
```bash
# Create route files
touch src/routes/documents.routes.js
touch src/routes/blog.routes.js
touch src/routes/auth.routes.js
touch src/routes/admin.routes.js
touch src/routes/index.js

# Create controllers
touch src/controllers/documents.controller.js
touch src/controllers/blog.controller.js
touch src/controllers/auth.controller.js
touch src/controllers/admin.controller.js
```

**Then implement:**
1. **Auth routes** first (login, verify token)
2. **Documents routes** (CRUD for framework docs)
3. **Blog routes** (public read, admin create)
4. **Admin routes** (moderation queue, stats)

**Update `src/server.js`:**
- Import routes from `src/routes/index.js`
- Mount under `/api`

### Option B: Document Migration Pipeline

**Start here:**
```bash
# Create migration script
touch scripts/migrate-documents.js
touch scripts/seed-admin.js
```

**Implement:**
1. Script to read markdown files from `docs/markdown/`
2. Parse with front matter extraction
3. Convert to HTML
4. Store in MongoDB via Document model
5. Verify migration worked

### Option C: Governance Services

**Note:** More complex, may want API routes first for testing

---

## Important Reminders

### Project Conventions (from CLAUDE.md)

**Ports:**
- MongoDB: 27017 (NOT 27027 like family-history)
- Application: 9000

**Separation:**
- This is SEPARATE from family-history and sydigital
- No shared code/dependencies
- Verify context before running any commands

**Quality Standards:**
- No shortcuts
- No fake data
- World-class quality
- All decisions align with TRA-VAL-0001

**Git Workflow:**
- Commit after each major feature
- Detailed commit messages
- Branch: main

### Values Framework

**All features must align with TRA-VAL-0001:**
- Sovereignty & Self-determination
- Transparency & Honesty
- Harmlessness & Protection
- Human Judgment Primacy
- Community & Accessibility

**Decision Framework:**
1. Does this require human approval? (If values-sensitive: YES)
2. Which quadrant? (STR/OPS/TAC/SYS/STO)
3. What's the AI role vs. human role?

### Te Tiriti Approach

**Strategic baseline, not dominant overlay:**
- Respect indigenous data sovereignty principles
- Use published standards (CARE Principles)
- No direct engagement until post-launch
- No tokenism

---

## File Locations Quick Reference

### Models
```
src/models/
├── Document.model.js       # Framework docs
├── BlogPost.model.js       # AI-curated blog
├── MediaInquiry.model.js   # Press/media
├── ModerationQueue.model.js # Human oversight
├── User.model.js           # Admin auth
├── CaseSubmission.model.js # Community submissions
├── Resource.model.js       # Curated directory
└── index.js               # Exports all
```

### Utilities
```
src/utils/
├── db.util.js         # MongoDB connection
├── logger.util.js     # Winston logging
├── jwt.util.js        # Token management
└── markdown.util.js   # Markdown processing
```

### Middleware
```
src/middleware/
├── auth.middleware.js       # JWT authentication
├── validation.middleware.js # Input validation
└── error.middleware.js      # Error handling
```

---

## Common Commands

```bash
# Start development server
npm run dev

# Initialize database (if needed)
npm run init:db

# Check MongoDB
mongosh mongodb://localhost:27017/tractatus_dev

# Git operations
git status
git log --oneline -5
git add -A
git commit -m "feat: description"

# MongoDB service
sudo systemctl status mongodb-tractatus
sudo systemctl restart mongodb-tractatus

# View logs
tail -f logs/app.log
tail -f logs/mongodb.log
```

---

## Testing Checklist

After implementing features:

```bash
# 1. Server starts without errors
npm run dev

# 2. Health check works
curl http://localhost:9000/health

# 3. API info works
curl http://localhost:9000/api

# 4. Test your new routes
curl http://localhost:9000/api/your-route

# 5. Check logs for errors
tail -20 logs/app.log
```

---

## Git Workflow

```bash
# Check status
git status

# Stage all changes
git add -A

# Commit with conventional commit format
git commit -m "feat: add API routes for documents

- Create documents.routes.js with CRUD endpoints
- Implement documents.controller.js with validation
- Add authentication middleware to protected routes
- Test all endpoints successfully

Status: Core API routes complete"

# View history
git log --oneline -5
```

---

## If Things Aren't Working

### MongoDB won't connect?
```bash
sudo systemctl status mongodb-tractatus
lsof -i :27017
tail -50 logs/mongodb.log
```

### Server won't start?
```bash
# Check if port is in use
lsof -i :9000

# Check environment
cat .env

# Check logs
tail -50 logs/app.log
```

### Database empty?
```bash
npm run init:db
mongosh mongodb://localhost:27017/tractatus_dev --eval "db.getCollectionNames()"
```

---

## Success Criteria for This Session

**Minimum:**
- Core API routes implemented and tested
- At least one document migrated successfully
- Server remains stable and operational

**Ideal:**
- All core API routes complete (auth, documents, blog, admin)
- Migration pipeline working
- Admin user seeded
- Start on governance services

**Quality:**
- All routes properly authenticated where needed
- Input validation on all endpoints
- Error handling tested
- Git commits for each feature
- No shortcuts, no fake data

---

## Contact & Decisions

**Human Approval Required For:**
- Architectural changes
- Database schema modifications
- Security implementations
- Third-party integrations
- Values-sensitive content
- Cost-incurring services

**If Uncertain:**
- Check TRA-VAL-0001 for values alignment
- Check CLAUDE.md for conventions
- Ask John Stroh for clarification

---

**Ready to Continue:** System verified, context loaded, next steps clear.

**Start with:** Verify environment → Read CLAUDE.md → Begin API routes

**End Goal:** Complete backend foundation (API + migration) before frontend development