# Multi-Project Governance System - Implementation Plan

**Project:** Tractatus Agentic Governance Framework
**Scope:** AI-Powered Rule Management + Multi-Project Infrastructure
**Standard:** World-class design and implementation
**Target:** Potential commercial product for Claude Code users

---

## 🎯 Executive Summary

Transform Tractatus from a single-project governance framework into a **multi-project, AI-powered governance platform** that:

1. **Replaces fragile CLAUDE.md** with validated, optimized governance rules
2. **Enables multi-project management** across portfolio with variable substitution
3. **Provides AI-assisted rule optimization** for clarity and effectiveness
4. **Offers project templates** for instant deployment to new projects
5. **Validates rules in real-time** using the 5 core Tractatus services

**Commercial Potential:** Solo developers to enterprise teams managing multiple AI-assisted projects

---

## 📐 System Architecture

### Three-Tier Rule System

```
┌─────────────────────────────────────────────────────┐
│ TIER 1: UNIVERSAL RULES                             │
│ • Apply to ALL projects                             │
│ • Contain variables: ${DB_PORT}, ${PROJECT_NAME}    │
│ • Example: "Database MUST use ${DB_TYPE}"           │
└─────────────────────────────────────────────────────┘
                        ↓ inherited by
┌─────────────────────────────────────────────────────┐
│ TIER 2: PROJECT-INHERITED RULES                     │
│ • Universal rules with project variables applied    │
│ • Tractatus: ${DB_TYPE} → MongoDB                   │
│ • SY Digital: ${DB_TYPE} → PostgreSQL               │
└─────────────────────────────────────────────────────┘
                        + combined with
┌─────────────────────────────────────────────────────┐
│ TIER 3: PROJECT-SPECIFIC RULES                      │
│ • Unique to one project                             │
│ • Example: "Blog posts MUST cite case studies"     │
└─────────────────────────────────────────────────────┘
```

### Core Components

```
Frontend (Vanilla JS + Tailwind)
├── Rule Manager Dashboard
├── Rule Editor with AI Assistant
├── Project Manager Dashboard
├── CLAUDE.md Migration Wizard
└── Project Configuration Editor

Backend (Node.js + Express)
├── Rule Management API
├── Project Management API
├── AI Services
│   ├── RuleOptimizer.service.js
│   ├── ClaudeMdAnalyzer.service.js
│   ├── RuleSuggestionEngine.service.js
│   └── RuleInterpolator.service.js
├── Validation Engine
│   └── RuleValidator.service.js (integrates 5 core services)
└── Template System

Database (MongoDB)
├── governanceRules (enhanced with scope, variables)
├── projects (NEW)
├── projectRules (NEW - overrides)
├── templates (NEW)
├── sessions (NEW - concurrent session support)
├── sessionState (NEW - session-specific state)
└── tokenCheckpoints (NEW - session milestones)
```

---

## 🗂️ Database Schema

### Enhanced `governanceRules` Collection

```javascript
{
  id: "univ_001",

  // NEW FIELDS for multi-project
  scope: "UNIVERSAL",              // UNIVERSAL | PROJECT_SPECIFIC
  applicableProjects: "*",         // "*" or ["tractatus", "family-history"]
  variables: ["DB_TYPE", "DB_PORT"], // Required variables for interpolation

  // Existing fields
  text: "Database connections MUST use ${DB_TYPE} on port ${DB_PORT}",
  quadrant: "SYSTEM",
  persistence: "HIGH",
  category: "technical",
  priority: 90,
  temporalScope: "PERMANENT",
  active: true,

  // NEW FIELDS for AI optimization
  clarityScore: 92,                // 0-100, AI-calculated
  specificityScore: 88,            // 0-100, AI-calculated
  actionabilityScore: 95,          // 0-100, AI-calculated
  lastOptimized: ISODate("2025-10-10"),
  optimizationHistory: [
    {
      timestamp: ISODate("2025-10-10"),
      before: "Database should use ${DB_TYPE}",
      after: "Database MUST use ${DB_TYPE} on port ${DB_PORT}",
      reason: "Changed weak language, added port parameter"
    }
  ],

  // Validation results
  validationStatus: "PASSED",      // PASSED | FAILED | NEEDS_REVIEW
  lastValidated: ISODate("2025-10-10"),
  validationResults: {
    classification: { passed: true, quadrant: "SYSTEM", persistence: "HIGH" },
    parameterExtraction: { passed: true, params: { DB_TYPE: "...", DB_PORT: "..." } },
    conflictDetection: { passed: true, conflicts: [] },
    boundaryCheck: { passed: true }
  },

  // Usage tracking
  usageStats: {
    referencedInProjects: ["tractatus", "family-history"],
    timesEnforced: 156,
    conflictsDetected: 3,
    lastEnforced: ISODate("2025-10-10")
  },

  // Standard metadata
  source: "user_instruction",
  createdBy: "theflow",
  createdAt: ISODate("2025-01-15"),
  updatedAt: ISODate("2025-10-10"),
  version: 2,
  notes: "Core database connection rule"
}
```

### NEW `projects` Collection

```javascript
{
  _id: ObjectId("..."),
  projectId: "tractatus",                    // Unique slug
  name: "Tractatus - Agentic Governance",
  description: "AI governance framework demonstration",
  active: true,

  // Domains
  domains: {
    production: "agenticgovernance.digital",
    mnemonics: ["ago.ovh"],
    staging: "staging.agenticgovernance.digital",
    development: "localhost:9000"
  },

  // Infrastructure
  infrastructure: {
    vps: {
      provider: "OVHCloud",
      host: "vps-93a693da.vps.ovh.net",
      ip: "51.210.xxx.xxx",
      user: "ubuntu",
      sshKeyPath: "/home/theflow/.ssh/tractatus_deploy",
      sshKeyEnvVar: "TRACTATUS_SSH_KEY",      // Reference to .env
      sshPort: 22
    },

    database: {
      type: "MongoDB",
      host: "localhost",
      port: 27017,
      name_dev: "tractatus_dev",
      name_test: "tractatus_test",
      name_prod: "tractatus_prod",
      authDatabase: "admin",
      backupSchedule: "daily-3am",
      backupRetention: "30-days"
    },

    repository: {
      url: "git@github.com:user/tractatus.git",
      branch_dev: "develop",
      branch_prod: "main",
      cicd: "GitHub Actions"
    },

    deployment: {
      method: "SSH + systemd",
      deployPath: "/var/www/tractatus",
      serviceName: "tractatus",
      serviceManager: "systemd",
      restartCommand: "sudo systemctl restart tractatus"
    }
  },

  // Application
  application: {
    runtime: "Node.js",
    version: "20.x",
    packageManager: "npm",
    port_dev: 9000,
    port_test: 9001,
    port_prod: 3000,
    framework: "Express",
    frontend: "Vanilla JS",
    styling: "Tailwind CSS",
    processManager: "systemd"
  },

  // Project Variables (used in rule interpolation)
  variables: {
    // Core identifiers
    PROJECT_NAME: "Tractatus",
    PROJECT_SLUG: "tractatus",
    PROJECT_DESCRIPTION: "Agentic Governance Framework",

    // Database
    DB_TYPE: "MongoDB",
    DB_PORT: "27017",
    DB_NAME_DEV: "tractatus_dev",
    DB_NAME_TEST: "tractatus_test",
    DB_NAME_PROD: "tractatus_prod",

    // Domains
    PROD_DOMAIN: "agenticgovernance.digital",
    PROD_URL: "https://agenticgovernance.digital",
    MNEMONIC_DOMAIN: "ago.ovh",

    // Infrastructure
    VPS_HOST: "vps-93a693da.vps.ovh.net",
    VPS_PROVIDER: "OVHCloud",
    SSH_USER: "ubuntu",
    SSH_KEY: "${ENV.TRACTATUS_SSH_KEY}",    // References .env
    DEPLOY_PATH: "/var/www/tractatus",

    // Application
    SERVICE_NAME: "tractatus",
    APP_PORT_DEV: "9000",
    APP_PORT_PROD: "3000",

    // Tech stack
    RUNTIME: "Node.js",
    FRAMEWORK: "Express",
    FRONTEND: "Vanilla JS",
    STYLING: "Tailwind CSS"
  },

  // Governance Configuration
  governance: {
    frameworkVersion: "1.0.0",
    universalRulesCount: 12,
    projectSpecificRulesCount: 6,
    totalActiveRules: 18,
    strictMode: true,
    auditRetention: "90-days",
    pressureMonitoring: true,
    metacognitiveVerification: true
  },

  // Team (for future expansion)
  team: {
    owner: "theflow",
    developers: ["theflow"],
    admins: ["theflow"]
  },

  // Related Projects
  relatedProjects: ["family-history", "sydigital"],
  templateId: "node-express-mongo",
  clonedFrom: null,                        // If cloned from another project

  // Deployment History
  deployments: [
    {
      timestamp: ISODate("2025-10-10T20:00:00Z"),
      version: "1.2.3",
      environment: "production",
      deployedBy: "theflow",
      status: "success",
      duration: "45s"
    }
  ],

  // Status
  status: "active",                         // active | paused | archived
  lastDeployed: ISODate("2025-10-10"),
  createdAt: ISODate("2025-01-15"),
  createdBy: "theflow",
  updatedAt: ISODate("2025-10-10")
}
```

### NEW `projectRules` Collection (Overrides)

```javascript
{
  _id: ObjectId("..."),
  projectId: "tractatus",
  ruleId: "univ_001",                      // References governanceRules

  // Overrides to universal rule
  overrides: {
    priority: 95,                          // Override universal priority (90 → 95)
    active: true,
    notes: "Critical for Tractatus - increased priority"
  },

  // Project-specific variable values
  variables: {
    DB_TYPE: "MongoDB",
    DB_PORT: "27017"
  },

  // Override metadata
  overriddenAt: ISODate("2025-10-10"),
  overriddenBy: "theflow",
  reason: "Database connection is critical for Tractatus"
}
```

### NEW `templates` Collection

```javascript
{
  _id: ObjectId("..."),
  templateId: "node-express-mongo",
  name: "Node.js + Express + MongoDB",
  description: "Full-stack JavaScript with MongoDB backend",
  category: "full-stack",

  // Default infrastructure
  defaultInfrastructure: {
    database: {
      type: "MongoDB",
      port: 27017
    },
    application: {
      runtime: "Node.js",
      framework: "Express",
      port_dev: 9000,
      port_prod: 3000
    }
  },

  // Default variables
  defaultVariables: {
    DB_TYPE: "MongoDB",
    DB_PORT: "27017",
    RUNTIME: "Node.js",
    FRAMEWORK: "Express"
  },

  // Universal rules included
  universalRules: [
    "univ_001",  // DB connection
    "univ_002",  // Port config
    "univ_003",  // Security boundaries
    "univ_004",  // Git workflow
    "univ_005",  // Testing requirements
    "univ_006",  // Code quality
    "univ_007",  // Documentation
    "univ_008",  // Error handling
    "univ_009",  // Authentication
    "univ_010",  // API design
    "univ_011",  // Deployment
    "univ_012"   // Monitoring
  ],

  // Template-specific suggested rules
  suggestedRules: [
    {
      text: "API endpoints MUST use Express Router pattern",
      quadrant: "SYSTEM",
      persistence: "HIGH",
      category: "technical"
    },
    {
      text: "MongoDB collections MUST use Mongoose models",
      quadrant: "SYSTEM",
      persistence: "HIGH",
      category: "technical"
    }
  ],

  // Files to generate
  scaffolding: {
    directories: [
      "src/models",
      "src/controllers",
      "src/routes",
      "src/services",
      "src/middleware",
      "public",
      "tests/unit",
      "tests/integration"
    ],
    files: [
      "package.json",
      ".env.example",
      "server.js",
      "README.md"
    ]
  },

  createdAt: ISODate("2025-10-10"),
  createdBy: "system",
  usageCount: 3
}
```

### NEW `sessions` Collection (Concurrent Session Support)

```javascript
{
  _id: ObjectId("..."),
  sessionId: "uuid-v4-abc-123",              // Unique session identifier
  projectId: "tractatus",                     // Which project this session is working on

  // Session metadata
  createdAt: ISODate("2025-10-10T14:30:00Z"),
  lastActive: ISODate("2025-10-10T15:45:00Z"),
  status: "active",                           // active | completed | abandoned

  // User/AI context
  initiatedBy: "theflow",
  aiModel: "claude-sonnet-4-5",
  purpose: "Implement concurrent session support",

  // Session metrics (isolated per session)
  metrics: {
    messageCount: 42,
    tokensUsed: 85000,
    tokensRemaining: 115000,
    tokenBudget: 200000,
    pressureLevel: "ELEVATED",              // NORMAL | ELEVATED | HIGH | DANGEROUS
    pressureScore: 42.5,                    // Percentage
    errorsRecent: 2,
    taskComplexity: "high"
  },

  // Framework activity (session-specific)
  frameworkActivity: {
    pressureChecks: 3,
    instructionsAdded: 2,
    validationsRun: 15,
    boundaryEnforcements: 1,
    metacognitiveVerifications: 8
  },

  // Checkpoints (when pressure checks were run)
  checkpoints: [
    { tokens: 50000, timestamp: ISODate("2025-10-10T14:45:00Z"), pressure: 25.0 },
    { tokens: 100000, timestamp: ISODate("2025-10-10T15:15:00Z"), pressure: 50.0 }
  ],

  // Related sessions (if forked or continued)
  parentSessionId: null,                     // If continued from compacted conversation
  childSessionIds: [],                       // If spawned sub-sessions

  // Completion metadata
  completedAt: null,
  completionReason: null,                    // budget_exhausted | handoff | task_complete

  // Indexes
  indexes: [
    { sessionId: 1 },                        // Unique
    { projectId: 1, status: 1 },
    { lastActive: 1 }
  ]
}
```

### NEW `sessionState` Collection (Session-Specific State)

```javascript
{
  _id: ObjectId("..."),
  sessionId: "uuid-v4-abc-123",              // References sessions collection

  // Current work context
  currentTask: {
    description: "Implement concurrent session support",
    startedAt: ISODate("2025-10-10T15:30:00Z"),
    filesModified: [
      "/home/theflow/projects/tractatus/docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md"
    ],
    complexity: "high"
  },

  // Active instructions for this session
  activeInstructions: [
    {
      instructionId: "inst_008",
      text: "HTML/JS files MUST NOT contain CSP violations",
      persistence: "HIGH",
      addedAt: ISODate("2025-10-10T14:30:00Z"),
      source: "instruction-history"
    }
  ],

  // Session-specific temporary rules (expires with session)
  temporaryRules: [
    {
      text: "Focus on database-backed state implementation",
      persistence: "SESSION",
      expiresAt: "session-end"
    }
  ],

  // Validation results (session-specific)
  validations: [
    {
      timestamp: ISODate("2025-10-10T15:00:00Z"),
      type: "cross_reference",
      action: "Edit file: implementation-plan.md",
      result: "APPROVED",
      conflicts: []
    }
  ],

  // Errors and warnings (session-specific)
  errors: [
    {
      timestamp: ISODate("2025-10-10T14:50:00Z"),
      type: "MongoServerError",
      message: "E11000 duplicate key error",
      resolved: true
    }
  ],

  // Last updated
  updatedAt: ISODate("2025-10-10T15:45:00Z"),

  // Indexes
  indexes: [
    { sessionId: 1 }                         // Unique
  ]
}
```

### NEW `tokenCheckpoints` Collection (Session Milestones)

```javascript
{
  _id: ObjectId("..."),
  sessionId: "uuid-v4-abc-123",

  // Checkpoint configuration
  tokenBudget: 200000,
  checkpoints: [
    { threshold: 50000, percentage: 25, label: "25%" },
    { threshold: 100000, percentage: 50, label: "50%" },
    { threshold: 150000, percentage: 75, label: "75%" }
  ],

  // Checkpoint execution history
  executedCheckpoints: [
    {
      threshold: 50000,
      executedAt: ISODate("2025-10-10T14:45:00Z"),
      tokensAtExecution: 50123,
      messagesAtExecution: 18,
      pressureLevel: "NORMAL",
      pressureScore: 25.1,
      reportedToUser: true,
      nextCheckpoint: 100000
    },
    {
      threshold: 100000,
      executedAt: ISODate("2025-10-10T15:15:00Z"),
      tokensAtExecution: 100456,
      messagesAtExecution: 35,
      pressureLevel: "ELEVATED",
      pressureScore: 50.2,
      reportedToUser: true,
      nextCheckpoint: 150000
    }
  ],

  // Next checkpoint
  nextCheckpoint: 150000,
  nextCheckpointPercentage: 75,

  // Framework fade detection
  frameworkFadeDetected: false,
  lastPressureCheck: ISODate("2025-10-10T15:15:00Z"),
  missedCheckpoints: [],

  // Metadata
  createdAt: ISODate("2025-10-10T14:30:00Z"),
  updatedAt: ISODate("2025-10-10T15:15:00Z"),

  // Indexes
  indexes: [
    { sessionId: 1 }                         // Unique
  ]
}
```

---

## 📁 File Structure

```
tractatus/
├── public/
│   └── admin/
│       ├── rule-manager.html           # Main rule dashboard
│       ├── rule-editor.html            # Detailed rule editor (modal)
│       ├── project-manager.html        # Project list/switcher
│       ├── project-config.html         # Project configuration
│       ├── claude-md-migrator.html     # CLAUDE.md analysis wizard
│       ├── rule-validator.html         # Rule validation results
│       └── project-templates.html      # Template library
│
├── public/js/admin/
│   ├── rule-manager.js                 # Rule CRUD + filtering
│   ├── rule-editor.js                  # Editor with AI suggestions
│   ├── rule-optimizer-ui.js            # AI optimization interface
│   ├── rule-validator-ui.js            # Real-time validation display
│   ├── project-manager.js              # Project CRUD
│   ├── project-config.js               # Config editor
│   ├── claude-md-migrator.js           # CLAUDE.md → rules
│   ├── variable-manager.js             # Variable editor
│   └── template-selector.js            # Template wizard
│
├── src/services/
│   ├── RuleOptimizer.service.js        # AI rule improvement
│   ├── ClaudeMdAnalyzer.service.js     # Parse CLAUDE.md
│   ├── RuleSuggestionEngine.service.js # Suggest rules from text
│   ├── RuleValidator.service.js        # Test rules against framework
│   ├── RuleInterpolator.service.js     # Variable substitution
│   ├── ProjectManager.service.js       # Project CRUD operations
│   └── TemplateManager.service.js      # Template operations
│
├── src/models/
│   ├── GovernanceRule.model.js         # Enhanced with scope/variables
│   ├── Project.model.js                # NEW
│   ├── ProjectRule.model.js            # NEW (overrides)
│   └── Template.model.js               # NEW
│
├── src/controllers/
│   ├── admin.controller.js             # Existing, expanded
│   ├── projects.controller.js          # NEW
│   ├── rules.controller.js             # NEW (extracted from admin)
│   └── templates.controller.js         # NEW
│
├── src/routes/
│   ├── admin.routes.js                 # Enhanced
│   ├── projects.routes.js              # NEW
│   ├── rules.routes.js                 # NEW
│   └── templates.routes.js             # NEW
│
├── scripts/
│   ├── analyze-claude-md.js            # CLI tool
│   ├── migrate-claude-md.js            # One-time migration
│   ├── validate-all-rules.js           # Bulk validation
│   └── export-project-config.js        # Export utility
│
└── docs/
    ├── MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md (this file)
    ├── API_REFERENCE.md                # API documentation
    ├── RULE_OPTIMIZATION_GUIDE.md      # How AI optimizer works
    └── PROJECT_TEMPLATES_GUIDE.md      # Template creation guide
```

---

## 🚀 Implementation Phases

---

## **PHASE 1: Core Rule Manager UI** (8-10 hours)

**Goal:** Build foundational rule management interface with CRUD operations

### 1.1 Backend - Enhanced Rule Model (1 hour)

**Tasks:**
- [ ] Update `GovernanceRule.model.js` schema
  - [ ] Add `scope` field (UNIVERSAL | PROJECT_SPECIFIC)
  - [ ] Add `variables` array field
  - [ ] Add `applicableProjects` field
  - [ ] Add `clarityScore`, `specificityScore`, `actionabilityScore`
  - [ ] Add `validationStatus`, `validationResults`
  - [ ] Add `usageStats` nested object
  - [ ] Add `optimizationHistory` array
- [ ] Create migration script for existing 18 rules
  - [ ] Set all existing rules to scope: "UNIVERSAL"
  - [ ] Initialize new fields with defaults
  - [ ] Test migration on tractatus_dev database
- [ ] Add indexes for new fields
  - [ ] Index on `scope`
  - [ ] Index on `clarityScore`
  - [ ] Index on `validationStatus`

**Files Modified:**
- `src/models/GovernanceRule.model.js`
- `scripts/migrations/001-enhance-governance-rules.js` (NEW)

**Success Criteria:**
- [ ] Schema updated without breaking existing functionality
- [ ] All 18 rules migrated successfully
- [ ] Database queries work with new fields

---

### 1.2 Backend - Rule Management API (2 hours)

**Tasks:**
- [ ] Create `src/controllers/rules.controller.js`
  - [ ] `GET /api/admin/rules` - List all rules
    - [ ] Support filtering: `?scope=UNIVERSAL&quadrant=SYSTEM&active=true`
    - [ ] Support sorting: `?sort=priority&order=desc`
    - [ ] Support pagination: `?page=1&limit=20`
    - [ ] Include computed fields: `interpolated` (if variables present)
  - [ ] `GET /api/admin/rules/:id` - Get single rule with full details
    - [ ] Include validation results
    - [ ] Include usage statistics
    - [ ] Include optimization history
  - [ ] `POST /api/admin/rules` - Create new rule
    - [ ] Validate required fields
    - [ ] Auto-detect variables in text (${VAR_NAME} pattern)
    - [ ] Set initial clarityScore (basic heuristics)
    - [ ] Trigger validation on creation
  - [ ] `PUT /api/admin/rules/:id` - Update rule
    - [ ] Track changes in optimizationHistory
    - [ ] Re-validate after update
    - [ ] Update clarityScore
  - [ ] `DELETE /api/admin/rules/:id` - Soft delete (set active: false)
    - [ ] Check if rule is in use by projects
    - [ ] Warn if deleting universal rule
  - [ ] `GET /api/admin/rules/stats` - Dashboard statistics
    - [ ] Count by scope, quadrant, persistence
    - [ ] Average clarity score
    - [ ] Total active vs inactive
- [ ] Create `src/routes/rules.routes.js`
  - [ ] Wire up all endpoints
  - [ ] Add authentication middleware
  - [ ] Add validation middleware
- [ ] Update `src/routes/index.js` to include rules routes

**Files Created:**
- `src/controllers/rules.controller.js`
- `src/routes/rules.routes.js`

**Files Modified:**
- `src/routes/index.js`

**Success Criteria:**
- [ ] All CRUD operations work via API
- [ ] Filtering and sorting work correctly
- [ ] Returns proper error messages
- [ ] Authenticated requests only

---

### 1.3 Frontend - Rule Manager Dashboard (3 hours)

**Tasks:**
- [ ] Create `public/admin/rule-manager.html`
  - [ ] Header with project selector (placeholder for Phase 3)
  - [ ] Filter panel
    - [ ] Scope dropdown (All | Universal | Project-Specific)
    - [ ] Quadrant dropdown
    - [ ] Persistence dropdown
    - [ ] Active/Inactive toggle
    - [ ] Search box (text search)
  - [ ] Sort controls
    - [ ] Sort by: Priority | Clarity Score | Last Modified | Name
    - [ ] Order: Ascending | Descending
  - [ ] Statistics cards
    - [ ] Total rules
    - [ ] By quadrant (pie chart)
    - [ ] Average clarity score
    - [ ] Rules needing review
  - [ ] Rule list/grid view
    - [ ] Each rule card shows:
      - [ ] Scope badge (Universal | Project)
      - [ ] Rule ID and text (truncated)
      - [ ] Quadrant + Persistence badges
      - [ ] Clarity score (visual bar)
      - [ ] Validation status icon
      - [ ] Variables (if any)
      - [ ] Actions: Edit | Validate | Delete
  - [ ] Pagination controls
  - [ ] "New Rule" button → opens editor modal

- [ ] Create `public/js/admin/rule-manager.js`
  - [ ] Fetch rules from API
  - [ ] Implement filtering logic
  - [ ] Implement sorting logic
  - [ ] Implement pagination
  - [ ] Render rule cards dynamically
  - [ ] Handle search with debouncing
  - [ ] Update statistics in real-time
  - [ ] Open editor modal on "Edit" click
  - [ ] Confirm before delete
  - [ ] Show success/error toasts

**Files Created:**
- `public/admin/rule-manager.html`
- `public/js/admin/rule-manager.js`

**Success Criteria:**
- [ ] Dashboard loads all 18 rules
- [ ] Filtering works for all criteria
- [ ] Sorting works correctly
- [ ] Search finds rules by text
- [ ] Statistics update when filters change
- [ ] Responsive design (mobile-friendly)

---

### 1.4 Frontend - Rule Editor Modal (2.5 hours)

**Tasks:**
- [ ] Create `public/admin/rule-editor.html` (modal component)
  - [ ] Left panel - Rule content
    - [ ] Text: Large textarea with syntax highlighting for ${VARS}
    - [ ] Scope: Radio buttons (Universal | Project-Specific)
    - [ ] Quadrant: Dropdown
    - [ ] Persistence: Dropdown
    - [ ] Category: Dropdown
    - [ ] Priority: Slider (1-100)
    - [ ] Temporal Scope: Dropdown
    - [ ] Active: Toggle
    - [ ] Examples: List with "Add Example" button
    - [ ] Notes: Textarea
  - [ ] Right panel - Preview & Info (Phase 2 will add AI suggestions)
    - [ ] Variables detected: List of ${VAR_NAME} found
    - [ ] Clarity score: Visual indicator (placeholder)
    - [ ] Preview: How rule looks when interpolated (Phase 3)
  - [ ] Footer
    - [ ] Cancel button
    - [ ] Save button
    - [ ] Save & Validate button

- [ ] Create `public/js/admin/rule-editor.js`
  - [ ] Initialize modal with rule data (edit mode) or blank (create mode)
  - [ ] Detect variables in text as user types
    - [ ] Regex: `/\$\{([A-Z_]+)\}/g`
    - [ ] Update variables list in real-time
  - [ ] Form validation
    - [ ] Required: text, scope, quadrant, persistence
    - [ ] Text must not be empty
    - [ ] If universal scope, must contain variables
  - [ ] Save rule via API
    - [ ] POST for new, PUT for update
    - [ ] Show loading state
    - [ ] Handle errors gracefully
  - [ ] Close modal on success
  - [ ] Refresh parent rule-manager list

**Files Created:**
- `public/admin/rule-editor.html`
- `public/js/admin/rule-editor.js`

**Success Criteria:**
- [ ] Can create new rules
- [ ] Can edit existing rules
- [ ] Variable detection works in real-time
- [ ] Form validation prevents bad data
- [ ] Modal closes and list refreshes on save
- [ ] Error messages are clear

---

### 1.5 Testing & Polish (1.5 hours)

**Tasks:**
- [ ] Manual testing
  - [ ] Create new rule from scratch
  - [ ] Edit existing rule
  - [ ] Delete rule (confirm it soft-deletes)
  - [ ] Filter by each criterion
  - [ ] Sort by each field
  - [ ] Search for rules
  - [ ] Test pagination with >20 rules (create dummy rules if needed)
- [ ] Error handling
  - [ ] Test API failures (disconnect network)
  - [ ] Test validation failures (invalid data)
  - [ ] Test edge cases (empty lists, no rules)
- [ ] UI Polish
  - [ ] Consistent styling with existing admin pages
  - [ ] Responsive design checks
  - [ ] Loading states for async operations
  - [ ] Toast notifications for success/error
  - [ ] Accessibility (keyboard navigation, ARIA labels)
- [ ] Documentation
  - [ ] Add comments to complex functions
  - [ ] Create basic user guide in README

**Success Criteria:**
- [ ] No bugs found in happy path
- [ ] Error cases handled gracefully
- [ ] UI is polished and professional
- [ ] Accessible and responsive

---

## **PHASE 2: AI Rule Optimizer & CLAUDE.md Analyzer** (10-12 hours)

**Goal:** Add intelligent rule optimization and CLAUDE.md migration

### 2.1 Backend - Rule Optimizer Service (3 hours)

**Tasks:**
- [ ] Create `src/services/RuleOptimizer.service.js`
  - [ ] **Clarity Analysis**
    - [ ] `analyzeClarity(ruleText)` → returns score 0-100
    - [ ] Detect vague language: "try", "maybe", "consider", "might"
    - [ ] Detect hedging: "probably", "possibly", "perhaps"
    - [ ] Detect weak imperatives: "should" vs "MUST"
    - [ ] Score based on: specificity, actionability, unambiguousness
  - [ ] **Specificity Analysis**
    - [ ] `analyzeSpecificity(ruleText)` → returns score 0-100
    - [ ] Check for concrete parameters: ports, paths, URLs
    - [ ] Check for explicit values vs generic terms
    - [ ] Detect "this project" → suggest explicit name
  - [ ] **Actionability Analysis**
    - [ ] `analyzeActionability(ruleText)` → returns score 0-100
    - [ ] Can a human/AI act on this without ambiguity?
    - [ ] Does it specify WHO, WHAT, WHEN, WHERE?
  - [ ] **Optimization Suggestions**
    - [ ] `suggestOptimizations(ruleText)` → returns array of suggestions
    - [ ] Suggest replacing weak language: "try to" → "MUST"
    - [ ] Suggest adding parameters: "use MongoDB" → "use MongoDB (port ${DB_PORT})"
    - [ ] Suggest replacing vague terms: "this project" → "${PROJECT_NAME} project (${TEMPORAL_SCOPE})"
    - [ ] Suggest removing hedging: "maybe consider" → "consider" or remove
  - [ ] **Auto-Optimize**
    - [ ] `optimize(ruleText, options)` → returns optimized text
    - [ ] Apply all suggestions automatically
    - [ ] Options: aggressive (applies all) vs conservative (applies safe ones)
    - [ ] Return before/after diff

**Algorithm Example:**
```javascript
analyzeClarity(text) {
  let score = 100;

  // Detect weak language
  const weakWords = ['try', 'maybe', 'consider', 'might', 'probably'];
  weakWords.forEach(word => {
    if (new RegExp(`\\b${word}\\b`, 'i').test(text)) {
      score -= 15;
    }
  });

  // Detect strong imperatives (bonus)
  const strongWords = ['MUST', 'SHALL', 'REQUIRED', 'PROHIBITED'];
  const hasStrong = strongWords.some(word =>
    new RegExp(`\\b${word}\\b`).test(text)
  );
  if (!hasStrong) score -= 10;

  // Check for specificity
  if (!/\$\{[A-Z_]+\}/.test(text)) score -= 10; // No variables
  if (!/\d/.test(text)) score -= 5; // No numbers

  return Math.max(0, Math.min(100, score));
}
```

**Files Created:**
- `src/services/RuleOptimizer.service.js`

**Success Criteria:**
- [ ] Clarity scoring is accurate (test with known good/bad rules)
- [ ] Suggestions are actionable and improve quality
- [ ] Auto-optimize produces better rules

---

### 2.2 Backend - CLAUDE.md Analyzer Service (3 hours)

**Tasks:**
- [ ] Create `src/services/ClaudeMdAnalyzer.service.js`
  - [ ] `parse(claudeMdContent)` → returns structured analysis
    - [ ] Extract sections by heading
    - [ ] Identify imperative statements (MUST, NEVER, ALWAYS)
    - [ ] Identify conditional statements (IF X THEN Y)
    - [ ] Identify preferences (SHOULD, TRY TO, PREFER)
  - [ ] `extractCandidateRules(parsedContent)` → returns rule candidates
    - [ ] For each imperative statement:
      - [ ] Extract as potential rule
      - [ ] Classify quadrant (keyword-based)
      - [ ] Suggest persistence (MUST→HIGH, SHOULD→MEDIUM, TRY→LOW)
      - [ ] Detect parameters (ports, paths, etc.)
      - [ ] Calculate initial clarity score
    - [ ] Categorize by quality:
      - [ ] ✅ High-quality: Specific, actionable, clear
      - [ ] ⚠️ Needs clarification: Vague, missing details
      - [ ] ❌ Too nebulous: "Be professional", "Do good work"
  - [ ] `detectRedundancies(candidates)` → returns merge suggestions
    - [ ] Find similar rules (text similarity >70%)
    - [ ] Suggest merging into single rule
  - [ ] `suggestImprovements(candidate)` → returns improvement suggestions
    - [ ] Use RuleOptimizer to analyze each candidate
    - [ ] Suggest specific improvements
  - [ ] `generateMigrationPlan(analysis)` → returns migration plan
    - [ ] List of rules to create
    - [ ] List of vague statements needing clarification
    - [ ] List of redundancies to merge

**Example Output:**
```javascript
{
  totalStatements: 45,
  candidateRules: [
    {
      originalText: "MongoDB port is 27017",
      suggestedRule: {
        text: "Database MUST use ${DB_TYPE} on port ${DB_PORT}",
        scope: "UNIVERSAL",
        quadrant: "SYSTEM",
        persistence: "HIGH",
        variables: ["DB_TYPE", "DB_PORT"],
        clarityScore: 92
      },
      quality: "HIGH",
      autoConvert: true
    },
    {
      originalText: "Try to maintain directory structure",
      suggestedRule: {
        text: "MUST preserve directory structure unless explicitly approved by user",
        scope: "UNIVERSAL",
        quadrant: "OPERATIONAL",
        persistence: "MEDIUM",
        clarityScore: 75
      },
      quality: "NEEDS_CLARIFICATION",
      autoConvert: false,
      improvements: [
        "Change 'Try to' to 'MUST'",
        "Add exception clause"
      ]
    },
    {
      originalText: "Be professional",
      quality: "TOO_NEBULOUS",
      autoConvert: false,
      suggestions: [
        "Split into specific rules:",
        "- Use formal tone in error messages",
        "- Avoid slang in user-facing text",
        "- Follow code style guide"
      ]
    }
  ],
  redundancies: [
    {
      rules: ["Use port 27017", "MongoDB port is 27017"],
      mergeSuggestion: "Database MUST use MongoDB on port 27017"
    }
  ]
}
```

**Files Created:**
- `src/services/ClaudeMdAnalyzer.service.js`

**Success Criteria:**
- [ ] Accurately extracts imperative statements from CLAUDE.md
- [ ] Classifies rules into quality tiers
- [ ] Detects redundancies
- [ ] Provides actionable improvement suggestions

---

### 2.3 Backend - API Endpoints for Optimization (1 hour)

**Tasks:**
- [ ] Add to `src/controllers/rules.controller.js`
  - [ ] `POST /api/admin/rules/:id/optimize` - Optimize single rule
    - [ ] Body: `{ mode: "aggressive" | "conservative" }`
    - [ ] Returns: optimized rule + diff + suggestions
  - [ ] `POST /api/admin/rules/analyze-claude-md` - Analyze CLAUDE.md
    - [ ] Body: `{ content: "..." }` (CLAUDE.md text)
    - [ ] Returns: full analysis with candidates
  - [ ] `POST /api/admin/rules/migrate-from-claude-md` - Create rules from analysis
    - [ ] Body: `{ selectedCandidates: [...] }`
    - [ ] Creates rules in database
    - [ ] Returns: created rule IDs

**Files Modified:**
- `src/controllers/rules.controller.js`
- `src/routes/rules.routes.js`

**Success Criteria:**
- [ ] Endpoints work and return expected data
- [ ] Optimization applies suggestions correctly
- [ ] CLAUDE.md analysis is comprehensive

---

### 2.4 Frontend - AI Optimization UI (3 hours)

**Tasks:**
- [ ] Enhance `public/admin/rule-editor.html` - Add AI Assistant Panel
  - [ ] Right panel now shows:
    - [ ] **Clarity Score**: Visual bar (0-100) with color coding
      - [ ] Green: 80-100
      - [ ] Yellow: 60-79
      - [ ] Red: 0-59
    - [ ] **Specificity Score**: Similar visual
    - [ ] **Actionability Score**: Similar visual
    - [ ] **Ambiguity Detected**: List of issues
      - [ ] "Weak language detected: 'try to'"
      - [ ] "Vague term: 'this project'"
    - [ ] **Suggested Improvements**: List with apply buttons
      - [ ] Each suggestion shows before/after
      - [ ] "Apply" button to auto-apply
      - [ ] "Apply All" button
    - [ ] **Optimization History**: Expandable list
      - [ ] Shows previous versions
      - [ ] Diff view
    - [ ] **"Run AI Optimizer"** button
      - [ ] Calls `/api/admin/rules/:id/optimize`
      - [ ] Shows loading spinner
      - [ ] Displays suggestions
      - [ ] Can apply automatically or review

- [ ] Update `public/js/admin/rule-editor.js`
  - [ ] Real-time clarity scoring as user types (debounced)
  - [ ] Call RuleOptimizer API on blur or button click
  - [ ] Display suggestions in UI
  - [ ] Apply suggestion on click
    - [ ] Update textarea
    - [ ] Re-score clarity
    - [ ] Add to optimization history
  - [ ] Show diff between original and optimized
    - [ ] Use diff library (e.g., `diff` npm package or simple highlight)

**Files Modified:**
- `public/admin/rule-editor.html`
- `public/js/admin/rule-editor.js`

**Success Criteria:**
- [ ] Real-time clarity scoring works
- [ ] AI suggestions appear and are actionable
- [ ] Can apply suggestions individually or all at once
- [ ] Optimization history tracks changes
- [ ] UI is intuitive and responsive

---

### 2.5 Frontend - CLAUDE.md Migration Wizard (2 hours)

**Tasks:**
- [ ] Create `public/admin/claude-md-migrator.html`
  - [ ] **Step 1: Upload CLAUDE.md**
    - [ ] File upload or paste textarea
    - [ ] "Analyze" button
  - [ ] **Step 2: Review Analysis**
    - [ ] Statistics
      - [ ] Total statements found: X
      - [ ] High-quality candidates: Y
      - [ ] Needs clarification: Z
      - [ ] Too nebulous: W
      - [ ] Redundancies detected: R
    - [ ] **High-Quality Rules** (Auto-convert recommended)
      - [ ] List with checkboxes (all checked by default)
      - [ ] Each shows:
        - [ ] Original statement
        - [ ] Suggested rule text
        - [ ] Quadrant/Persistence
        - [ ] Clarity score
    - [ ] **Needs Clarification** (Review required)
      - [ ] List with checkboxes (unchecked by default)
      - [ ] Each shows:
        - [ ] Original statement
        - [ ] Suggested improvements
        - [ ] Can edit inline before creating
    - [ ] **Too Nebulous** (Manual action required)
      - [ ] List (not selectable for auto-creation)
      - [ ] Shows suggestions for how to split/improve
    - [ ] **Redundancies** (Merge suggestions)
      - [ ] Groups of similar rules
      - [ ] Suggested merged version
      - [ ] Can edit merged rule
  - [ ] **Step 3: Create Rules**
    - [ ] "Create Selected Rules" button
    - [ ] Progress bar as rules are created
    - [ ] Success summary: "Created 12 rules, 3 need manual review"

- [ ] Create `public/js/admin/claude-md-migrator.js`
  - [ ] Handle file upload or paste
  - [ ] Call `/api/admin/rules/analyze-claude-md`
  - [ ] Render analysis results
  - [ ] Allow editing of suggested rules
  - [ ] Batch create selected rules via `/api/admin/rules/migrate-from-claude-md`
  - [ ] Show progress and results

**Files Created:**
- `public/admin/claude-md-migrator.html`
- `public/js/admin/claude-md-migrator.js`

**Success Criteria:**
- [ ] Can upload current CLAUDE.md and get analysis
- [ ] Analysis categorizes rules correctly
- [ ] Can review and edit before creating
- [ ] Batch creation works
- [ ] Clear feedback on success/failures

---

### 2.6 Testing & Validation (1 hour)

**Tasks:**
- [ ] Test RuleOptimizer with sample rules
  - [ ] Good rule: Should score high clarity
  - [ ] Vague rule: Should score low and suggest improvements
  - [ ] Apply suggestions and verify improvement
- [ ] Test CLAUDE.md Analyzer
  - [ ] Analyze actual CLAUDE.md from project
  - [ ] Verify candidates are sensible
  - [ ] Check redundancy detection
- [ ] Test Migration Wizard
  - [ ] Upload CLAUDE.md
  - [ ] Review suggestions
  - [ ] Create rules
  - [ ] Verify rules appear in rule manager
- [ ] Edge cases
  - [ ] Empty CLAUDE.md
  - [ ] Malformed content
  - [ ] Already-perfect rules (shouldn't suggest changes)

**Success Criteria:**
- [ ] No bugs in optimization flow
- [ ] CLAUDE.md analysis is accurate
- [ ] Migration creates valid rules
- [ ] Edge cases handled gracefully

---

## **PHASE 3: Multi-Project Infrastructure** (10-12 hours)

**Goal:** Enable management of multiple projects with variable substitution

### 3.1 Backend - Project Model & API (3 hours)

**Tasks:**
- [ ] Create `src/models/Project.model.js`
  - [ ] Define schema (as shown in Database Schema section)
  - [ ] Add static methods
    - [ ] `findBySlug(slug)`
    - [ ] `findActive()`
    - [ ] `findByTemplate(templateId)`
  - [ ] Add instance methods
    - [ ] `getVariables()` - return project variables
    - [ ] `getRules()` - return all rules (universal + project-specific)
    - [ ] `deploy()` - trigger deployment (placeholder for now)
  - [ ] Add virtuals
    - [ ] `totalRules` - count of active rules

- [ ] Create `src/models/ProjectRule.model.js`
  - [ ] Schema for project-specific overrides
  - [ ] Reference governanceRules and projects

- [ ] Create `src/controllers/projects.controller.js`
  - [ ] `GET /api/admin/projects` - List all projects
    - [ ] Support filtering: `?active=true&template=node-express-mongo`
    - [ ] Include rule counts
  - [ ] `GET /api/admin/projects/:id` - Get project with full config
    - [ ] Include variables
    - [ ] Include infrastructure
    - [ ] Include rule counts (universal + custom)
  - [ ] `POST /api/admin/projects` - Create new project
    - [ ] Validate required fields
    - [ ] Initialize default variables
    - [ ] Link universal rules
    - [ ] Return created project
  - [ ] `PUT /api/admin/projects/:id` - Update project
    - [ ] Allow updating variables, infrastructure, metadata
    - [ ] Validate variable changes don't break rules
  - [ ] `DELETE /api/admin/projects/:id` - Soft delete (set active: false)
    - [ ] Warn if project has custom rules
  - [ ] `GET /api/admin/projects/:id/rules` - Get all rules for project
    - [ ] Return universal rules + project-specific
    - [ ] Interpolate variables
  - [ ] `POST /api/admin/projects/:id/rules` - Add custom rule to project
  - [ ] `PUT /api/admin/projects/:id/rules/:ruleId/override` - Override universal rule

- [ ] Create `src/routes/projects.routes.js`
  - [ ] Wire up all endpoints
  - [ ] Add authentication

**Files Created:**
- `src/models/Project.model.js`
- `src/models/ProjectRule.model.js`
- `src/controllers/projects.controller.js`
- `src/routes/projects.routes.js`

**Files Modified:**
- `src/routes/index.js`

**Success Criteria:**
- [ ] Can create projects via API
- [ ] Can retrieve projects with all details
- [ ] Can update project configurations
- [ ] Rules are correctly associated with projects

---

### 3.2 Backend - Rule Interpolator Service (2 hours)

**Tasks:**
- [ ] Create `src/services/RuleInterpolator.service.js`
  - [ ] `interpolate(rule, projectVariables)` → returns expanded rule
    - [ ] Find all `${VAR_NAME}` patterns
    - [ ] Replace with project variable values
    - [ ] Throw error if variable not defined
    - [ ] Return new rule object with `interpolated: true`
  - [ ] `interpolateRules(rules, projectVariables)` → bulk interpolation
  - [ ] `validateVariables(ruleText, availableVariables)` → check if all vars defined
  - [ ] `extractRequiredVariables(ruleText)` → return array of var names
  - [ ] `previewAcrossProjects(ruleId)` → show how rule looks in all projects
    - [ ] Fetch rule and all active projects
    - [ ] Interpolate for each project
    - [ ] Return array of { projectName, expandedRule }

**Example:**
```javascript
interpolate(rule, variables) {
  let text = rule.text;
  const varPattern = /\$\{([A-Z_]+)\}/g;
  const matches = Array.from(text.matchAll(varPattern));

  for (const match of matches) {
    const varName = match[1];

    // Handle env var references: ${ENV.VAR_NAME}
    if (varName.startsWith('ENV.')) {
      const envVar = varName.replace('ENV.', '');
      const value = process.env[envVar];
      if (!value) {
        throw new Error(`Environment variable ${envVar} not set`);
      }
      text = text.replace(match[0], value);
    }
    // Normal project variable
    else {
      const value = variables[varName];
      if (!value) {
        throw new Error(`Variable ${varName} not defined for project`);
      }
      text = text.replace(match[0], value);
    }
  }

  return { ...rule, text, originalText: rule.text, interpolated: true };
}
```

**Files Created:**
- `src/services/RuleInterpolator.service.js`

**Success Criteria:**
- [ ] Variable substitution works correctly
- [ ] Handles missing variables with clear errors
- [ ] Environment variable references work
- [ ] Can preview rules across all projects

---

### 3.3 Backend - Seed Initial Projects (1 hour)

**Tasks:**
- [ ] Create `scripts/seed-projects.js`
  - [ ] Create Tractatus project
    - [ ] Use existing configuration
    - [ ] Map all current rules to it
  - [ ] Create template projects for reference
    - [ ] Family History (placeholder)
    - [ ] SY Digital (placeholder)
  - [ ] Create universal rules
    - [ ] Migrate existing 18 rules or subset to universal
    - [ ] Add variables where appropriate

- [ ] Run seed script
  - [ ] Test on tractatus_dev
  - [ ] Verify projects created
  - [ ] Verify rules linked correctly

**Files Created:**
- `scripts/seed-projects.js`

**Success Criteria:**
- [ ] Tractatus project exists in database
- [ ] Rules are correctly associated
- [ ] Can query rules for Tractatus project

---

### 3.4 Frontend - Project Switcher (1 hour)

**Tasks:**
- [ ] Update all admin pages headers
  - [ ] Add project dropdown in top nav
  - [ ] Current project shown prominently
  - [ ] Dropdown lists all active projects
  - [ ] Clicking project switches context
  - [ ] Store selected project in localStorage
  - [ ] "Manage Projects" link → project manager

- [ ] Create `public/js/admin/project-switcher.js`
  - [ ] Fetch projects from API
  - [ ] Render dropdown
  - [ ] Handle project selection
  - [ ] Update localStorage: `currentProjectId`
  - [ ] Refresh page content for new project

**Files Modified:**
- `public/admin/rule-manager.html` (add project switcher)
- `public/admin/rule-editor.html` (add project switcher)
- All other admin pages

**Files Created:**
- `public/js/admin/project-switcher.js`

**Success Criteria:**
- [ ] Project switcher appears on all admin pages
- [ ] Switching projects updates UI
- [ ] Current project persists across page reloads

---

### 3.5 Frontend - Project Manager Dashboard (2.5 hours)

**Tasks:**
- [ ] Create `public/admin/project-manager.html`
  - [ ] Project list/grid
    - [ ] Each project card shows:
      - [ ] Project name
      - [ ] Primary domain
      - [ ] Rule counts (universal + custom)
      - [ ] Last deployed
      - [ ] Status (active/paused)
      - [ ] Actions: Edit | Deploy | Clone | Delete
  - [ ] "New Project" button → opens project wizard
  - [ ] Statistics
    - [ ] Total projects
    - [ ] Total rules across all projects
    - [ ] Projects by template

- [ ] Create `public/js/admin/project-manager.js`
  - [ ] Fetch projects from API
  - [ ] Render project cards
  - [ ] Handle edit (open config editor)
  - [ ] Handle delete (confirm + API call)
  - [ ] Handle clone (Phase 5)
  - [ ] Handle deploy (placeholder for now)

**Files Created:**
- `public/admin/project-manager.html`
- `public/js/admin/project-manager.js`

**Success Criteria:**
- [ ] Lists all projects
- [ ] Can navigate to project config editor
- [ ] Can delete projects with confirmation
- [ ] Shows accurate statistics

---

### 3.6 Frontend - Project Configuration Editor (2.5 hours)

**Tasks:**
- [ ] Create `public/admin/project-config.html`
  - [ ] Tabs:
    - [ ] **Overview**
      - [ ] Name (editable)
      - [ ] Description (editable)
      - [ ] Status (active/paused toggle)
      - [ ] Domains (list, can add/remove)
    - [ ] **Infrastructure**
      - [ ] VPS config (host, user, SSH key)
      - [ ] Database config (type, port, name)
      - [ ] Repository config (URL, branches)
      - [ ] Deployment config (path, service name)
    - [ ] **Variables**
      - [ ] List of all variables
      - [ ] Each row: Variable Name | Value | Used in X rules
      - [ ] "Add Variable" button
      - [ ] Can edit inline
      - [ ] Preview rule expansion on hover
    - [ ] **Rules**
      - [ ] List inherited universal rules (read-only, but can override)
      - [ ] List project-specific rules (can edit/delete)
      - [ ] "Add Custom Rule" button
      - [ ] Each rule shows:
        - [ ] Scope badge
        - [ ] Text (interpolated if universal)
        - [ ] Quadrant/Persistence
        - [ ] Actions: Edit | Delete (for custom) | Override (for universal)
    - [ ] **Deployment**
      - [ ] Deployment history table
      - [ ] "Deploy Now" button (placeholder)
  - [ ] Save button (applies to all tabs)

- [ ] Create `public/js/admin/project-config.js`
  - [ ] Load project via API
  - [ ] Render tabs
  - [ ] Handle inline editing
  - [ ] Variable management
    - [ ] Add/remove variables
    - [ ] Validate variable names (uppercase, underscores)
    - [ ] Warn if removing variable used in rules
  - [ ] Rule overrides
    - [ ] Open override modal for universal rules
    - [ ] Save overrides via API
  - [ ] Save all changes via PUT /api/admin/projects/:id

**Files Created:**
- `public/admin/project-config.html`
- `public/js/admin/project-config.js`

**Success Criteria:**
- [ ] Can edit all project configuration
- [ ] Variables can be added/removed/edited
- [ ] Rules are correctly displayed (interpolated)
- [ ] Changes save successfully
- [ ] UI prevents invalid states (e.g., removing used variables)

---

### 3.7 Testing & Integration (1 hour)

**Tasks:**
- [ ] Create second test project
  - [ ] Different variables (e.g., PostgreSQL instead of MongoDB)
  - [ ] Verify rule interpolation works
- [ ] Switch between projects
  - [ ] Verify rules update correctly
  - [ ] Verify variables are project-specific
- [ ] Test variable changes
  - [ ] Change a variable value
  - [ ] Verify interpolated rules update
- [ ] Test edge cases
  - [ ] Variable referenced but not defined (should error)
  - [ ] Environment variables (${ENV.VAR})
  - [ ] Empty project (no custom rules)

**Success Criteria:**
- [ ] Multi-project system works seamlessly
- [ ] Variable interpolation is accurate
- [ ] No cross-project data leakage
- [ ] Error handling is robust

---

## **PHASE 3.5: Concurrent Session Architecture** (4-6 hours)

**Goal:** Enable multiple concurrent Claude Code sessions without state contamination

**Context:** Addresses architectural limitation discovered during production testing ([concurrent-session-architecture-limitations.md](/home/theflow/projects/tractatus/docs/research/concurrent-session-architecture-limitations.md)). Current file-based session state (`.claude/*.json`) causes contamination when multiple sessions run concurrently. Solution: Migrate to database-backed session state.

### 3.5.1 Backend - Session Models (1 hour)

**Tasks:**
- [ ] Create `src/models/Session.model.js`
  - [ ] Schema (as shown in Database Schema section above)
  - [ ] Static methods:
    - [ ] `findActive()` - get all active sessions
    - [ ] `findByProject(projectId)` - sessions for specific project
    - [ ] `createWithUUID()` - generate unique session ID (uuid-v4)
  - [ ] Instance methods:
    - [ ] `updateMetrics(tokenCount, messageCount)` - update session metrics
    - [ ] `recordCheckpoint(tokens, pressure)` - record pressure checkpoint
    - [ ] `complete(reason)` - mark session as completed
  - [ ] Indexes:
    - [ ] Unique index on `sessionId`
    - [ ] Compound index on `projectId` + `status`
    - [ ] Index on `lastActive` for cleanup

- [ ] Create `src/models/SessionState.model.js`
  - [ ] Schema (as shown in Database Schema section)
  - [ ] Stores active instructions, validations, errors per session
  - [ ] Index on `sessionId` (unique)

- [ ] Create `src/models/TokenCheckpoint.model.js`
  - [ ] Schema (as shown in Database Schema section)
  - [ ] Tracks checkpoints and framework fade detection
  - [ ] Index on `sessionId` (unique)

**Files Created:**
- `src/models/Session.model.js`
- `src/models/SessionState.model.js`
- `src/models/TokenCheckpoint.model.js`

**Success Criteria:**
- [ ] Models created with proper schemas
- [ ] Indexes configured correctly
- [ ] Can create/query session documents

---

### 3.5.2 Backend - Session Management Service (1.5 hours)

**Tasks:**
- [ ] Create `src/services/SessionManager.service.js`
  - [ ] `initializeSession(projectId, purpose)` → creates new session
    - [ ] Generate UUID v4 for session ID
    - [ ] Create Session document
    - [ ] Create SessionState document
    - [ ] Create TokenCheckpoint document
    - [ ] Return session ID
  - [ ] `getSessionMetrics(sessionId)` → returns current metrics
    - [ ] Fetch from Session.metrics
    - [ ] Calculate pressure score
    - [ ] Return isolated metrics (not contaminated)
  - [ ] `updateSessionActivity(sessionId, data)` → updates session
    - [ ] Update tokensUsed, messageCount, errors
    - [ ] Update lastActive timestamp
    - [ ] Recalculate pressure level
  - [ ] `recordPressureCheckpoint(sessionId, tokens, pressure)` → logs checkpoint
    - [ ] Append to Session.checkpoints
    - [ ] Update TokenCheckpoint.executedCheckpoints
    - [ ] Detect framework fade if missed checkpoint
  - [ ] `addInstruction(sessionId, instruction)` → add to session
    - [ ] Append to SessionState.activeInstructions
    - [ ] No file writes (database only)
  - [ ] `recordValidation(sessionId, validation)` → log validation result
    - [ ] Append to SessionState.validations
  - [ ] `completeSession(sessionId, reason)` → close session
    - [ ] Update Session.status = 'completed'
    - [ ] Set Session.completedAt
    - [ ] Archive metrics for analysis
  - [ ] `cleanupOldSessions(daysOld)` → remove stale sessions
    - [ ] Find sessions older than N days
    - [ ] Archive to cold storage (optional)
    - [ ] Delete from active collections

**Files Created:**
- `src/services/SessionManager.service.js`

**Success Criteria:**
- [ ] Can create isolated sessions with unique IDs
- [ ] Metrics are session-specific (no contamination)
- [ ] Concurrent sessions don't interfere
- [ ] Old sessions can be cleaned up

---

### 3.5.3 Scripts - Migrate Session Init to Database (1 hour)

**Tasks:**
- [ ] Update `scripts/session-init.js`
  - [ ] Check if session ID exists in `.claude/session-state.json`
  - [ ] If yes (continued session): Load from MongoDB using existing ID
  - [ ] If no (new session): Create new session via SessionManager
  - [ ] Initialize ContextPressureMonitor with session ID
  - [ ] Update other 4 framework components to use session ID
  - [ ] **Still write** `.claude/session-state.json` (for backward compatibility)
    - [ ] Store only sessionId reference
    - [ ] Actual state lives in MongoDB
  - [ ] Report session ID to user

- [ ] Update `scripts/check-session-pressure.js`
  - [ ] Read session ID from `.claude/session-state.json`
  - [ ] Fetch current metrics from MongoDB (not file)
  - [ ] Calculate pressure using session-specific data
  - [ ] Update MongoDB (not file)
  - [ ] Report to user with session ID

- [ ] Create `scripts/list-active-sessions.js` (diagnostic tool)
  - [ ] Query MongoDB for all active sessions
  - [ ] Display: sessionId, projectId, tokensUsed, pressureLevel, lastActive
  - [ ] Help user understand concurrent session state

**Files Modified:**
- `scripts/session-init.js`
- `scripts/check-session-pressure.js`

**Files Created:**
- `scripts/list-active-sessions.js`

**Success Criteria:**
- [ ] Session initialization uses database
- [ ] Backward compatible with existing file structure
- [ ] Pressure checks use isolated session metrics
- [ ] Can list all active sessions

---

### 3.5.4 Framework Integration - Update Core Services (1 hour)

**Tasks:**
- [ ] Update `src/services/ContextPressureMonitor.service.js`
  - [ ] Accept sessionId in `initialize(sessionId)`
  - [ ] Load metrics from MongoDB instead of file
  - [ ] Update metrics to MongoDB instead of file
  - [ ] Calculate pressure using session-specific data only

- [ ] Update `src/services/InstructionPersistenceClassifier.service.js`
  - [ ] Store new instructions in MongoDB SessionState
  - [ ] **ALSO append** to `.claude/instruction-history.json` (shared state)
    - [ ] Use file locking to prevent race conditions
    - [ ] Instruction history is shared across all sessions
    - [ ] Session state is isolated per session

- [ ] Update `src/services/MetacognitiveVerifier.service.js`
  - [ ] Store verification logs in MongoDB VerificationLog (already done)
  - [ ] Ensure sessionId is included in all log entries

- [ ] Update `src/services/CrossReferenceValidator.service.js`
  - [ ] No changes needed (reads shared instruction history)

- [ ] Update `src/services/BoundaryEnforcer.service.js`
  - [ ] No changes needed (stateless)

**Files Modified:**
- `src/services/ContextPressureMonitor.service.js`
- `src/services/InstructionPersistenceClassifier.service.js`
- `src/services/MetacognitiveVerifier.service.js`

**Success Criteria:**
- [ ] All 5 framework components session-aware
- [ ] Shared state (instruction history) uses file locking
- [ ] Isolated state (session metrics) uses MongoDB
- [ ] No cross-session contamination

---

### 3.5.5 Testing - Concurrent Session Tests (0.5 hour)

**Tasks:**
- [ ] Create `tests/integration/concurrent-sessions.test.js`
  - [ ] **Test: Isolated Metrics**
    - [ ] Create two sessions (A, B)
    - [ ] Update A with 50k tokens, 20 messages
    - [ ] Update B with 100k tokens, 40 messages
    - [ ] Verify A metrics show 50k tokens (not 150k)
    - [ ] Verify B metrics show 100k tokens (not 150k)
  - [ ] **Test: Independent Pressure Calculations**
    - [ ] Session A at 25% usage → NORMAL pressure
    - [ ] Session B at 75% usage → HIGH pressure
    - [ ] Verify A reports NORMAL (not contaminated by B)
  - [ ] **Test: Shared Instruction History**
    - [ ] Session A adds instruction "Use MongoDB"
    - [ ] Session B can see instruction in shared history
    - [ ] Verify instruction-history.json contains it
  - [ ] **Test: Session-Specific Validations**
    - [ ] Session A runs validation
    - [ ] Session B runs validation
    - [ ] Verify validations stored separately in MongoDB
  - [ ] **Test: Concurrent Test Suite Execution**
    - [ ] Run test suite in Session A
    - [ ] Simultaneously run test suite in Session B
    - [ ] Verify no MongoDB duplicate key errors
    - [ ] Verify tests pass in both sessions

**Files Created:**
- `tests/integration/concurrent-sessions.test.js`

**Success Criteria:**
- [ ] All concurrency tests pass
- [ ] No metric contamination
- [ ] No database conflicts
- [ ] Sessions can run simultaneously

---

### 3.5.6 Documentation & Migration Guide (0.5 hour)

**Tasks:**
- [ ] Create `docs/CONCURRENT_SESSIONS_GUIDE.md`
  - [ ] Explain the problem (file-based state contamination)
  - [ ] Explain the solution (database-backed session state)
  - [ ] Architecture diagram:
    - [ ] Shared state: instruction-history.json (file-locked)
    - [ ] Isolated state: MongoDB sessions/sessionState/tokenCheckpoints
  - [ ] How to use:
    - [ ] Run `node scripts/session-init.js` as normal
    - [ ] Session ID auto-generated (or continued)
    - [ ] Multiple sessions can run concurrently
  - [ ] Diagnostics:
    - [ ] `node scripts/list-active-sessions.js` to see all sessions
    - [ ] How to debug session contamination
  - [ ] Migration notes:
    - [ ] Existing `.claude/*.json` files still used
    - [ ] Backward compatible
    - [ ] Old sessions auto-migrated on first use

- [ ] Update `CLAUDE_Tractatus_Maintenance_Guide.md`
  - [ ] Add section on concurrent session support
  - [ ] Document session ID usage
  - [ ] Update troubleshooting guide

**Files Created:**
- `docs/CONCURRENT_SESSIONS_GUIDE.md`

**Files Modified:**
- `CLAUDE_Tractatus_Maintenance_Guide.md`

**Success Criteria:**
- [ ] Clear documentation of architecture
- [ ] Migration guide for users
- [ ] Troubleshooting instructions

---

### 3.5.7 Testing & Validation (0.5 hour)

**Tasks:**
- [ ] Manual testing
  - [ ] Start two concurrent Claude Code sessions
  - [ ] Verify each gets unique session ID
  - [ ] Work in both sessions simultaneously
  - [ ] Check metrics don't contaminate
  - [ ] Run `scripts/list-active-sessions.js`
- [ ] Production scenario testing
  - [ ] Run test suite in one session
  - [ ] Do development work in another session
  - [ ] Verify no duplicate key errors
  - [ ] Verify test isolation works
- [ ] Framework fade detection
  - [ ] Simulate missed checkpoint in one session
  - [ ] Verify only that session reports fade (not others)
- [ ] Cleanup testing
  - [ ] Create old sessions
  - [ ] Run cleanup script
  - [ ] Verify only old sessions removed

**Success Criteria:**
- [ ] Concurrent sessions work flawlessly
- [ ] No state contamination observed
- [ ] Framework components function correctly
- [ ] Cleanup works as expected

---

**Phase 3.5 Summary:**

This phase solves the **single-tenant architecture limitation** by migrating to database-backed session state while preserving backward compatibility with file-based instruction history. After this phase:

✅ Multiple Claude Code sessions can run concurrently
✅ Each session has isolated metrics (tokens, messages, pressure)
✅ Shared instruction history remains accessible to all sessions
✅ Test suites can run without conflicts
✅ Framework fade detection works per-session
✅ Production + development can run simultaneously

**References:**
- [Concurrent Session Architecture Limitations](/home/theflow/projects/tractatus/docs/research/concurrent-session-architecture-limitations.md)
- Database schemas: `sessions`, `sessionState`, `tokenCheckpoints` (defined above)

---

## **PHASE 4: Rule Validation Engine & Testing** (8-10 hours)

**Goal:** Real-time rule validation using Tractatus framework services

### 4.1 Backend - Rule Validator Service (4 hours)

**Tasks:**
- [ ] Create `src/services/RuleValidator.service.js`
  - [ ] `validateRule(rule, projectContext)` → comprehensive validation
    - [ ] **Classification Test**
      - [ ] Use InstructionPersistenceClassifier.classify()
      - [ ] Check if classified quadrant matches rule.quadrant
      - [ ] Check if classified persistence matches rule.persistence
      - [ ] Verify parameters extracted correctly
    - [ ] **Parameter Extraction Test**
      - [ ] Use InstructionPersistenceClassifier._extractParameters()
      - [ ] Verify expected parameters are found
      - [ ] Check for false positives (shouldn't extract non-params)
    - [ ] **Conflict Detection Test**
      - [ ] Use CrossReferenceValidator.validate()
      - [ ] Test rule against other active rules
      - [ ] Check for contradictions
    - [ ] **Boundary Test**
      - [ ] Use BoundaryEnforcer.enforce()
      - [ ] Verify rule doesn't violate Tractatus boundaries
      - [ ] Check for values decisions (should be flagged)
    - [ ] **Metacognitive Verification Test** (optional, for complex rules)
      - [ ] Use MetacognitiveVerifier.verify()
      - [ ] Check reasoning quality if rule has examples
    - [ ] Return comprehensive result:
      ```javascript
      {
        passed: true,
        tests: {
          classification: {
            passed: true,
            expected: { quadrant: 'SYSTEM', persistence: 'HIGH' },
            actual: { quadrant: 'SYSTEM', persistence: 'HIGH' },
            parameterMatch: true
          },
          parameterExtraction: {
            passed: true,
            params: { port: '27017', db_type: 'MongoDB' }
          },
          conflictDetection: {
            passed: true,
            conflicts: []
          },
          boundaryCheck: {
            passed: true,
            allowed: true
          }
        },
        score: 95,  // 0-100
        warnings: [],
        errors: []
      }
      ```

  - [ ] `validateBatch(rules, projectContext)` → validate multiple rules
  - [ ] `generateTestCase(rule)` → auto-generate test for rule
    - [ ] Create instruction object
    - [ ] Create expected classification
    - [ ] Create conflicting action (for conflict test)
    - [ ] Return test case that can be run later

**Integration:**
- [ ] Use existing 5 core services:
  - [ ] InstructionPersistenceClassifier
  - [ ] CrossReferenceValidator
  - [ ] BoundaryEnforcer
  - [ ] ContextPressureMonitor (for pressure-aware validation)
  - [ ] MetacognitiveVerifier

**Files Created:**
- `src/services/RuleValidator.service.js`

**Success Criteria:**
- [ ] Validation integrates all 5 services
- [ ] Catches classification mismatches
- [ ] Detects conflicts between rules
- [ ] Identifies boundary violations
- [ ] Returns actionable results

---

### 4.2 Backend - Validation API Endpoints (1 hour)

**Tasks:**
- [ ] Add to `src/controllers/rules.controller.js`
  - [ ] `POST /api/admin/rules/:id/validate` - Validate single rule
    - [ ] Query param: `?projectId=tractatus` (optional)
    - [ ] Runs all validation tests
    - [ ] Updates rule's `validationStatus` and `validationResults` in DB
    - [ ] Returns results
  - [ ] `POST /api/admin/rules/validate-all` - Validate all rules
    - [ ] Query param: `?projectId=tractatus` (optional)
    - [ ] Runs validation for all active rules
    - [ ] Returns summary + individual results
  - [ ] `POST /api/admin/rules/:id/test` - Run generated test case
    - [ ] Executes auto-generated test
    - [ ] Returns pass/fail

**Files Modified:**
- `src/controllers/rules.controller.js`
- `src/routes/rules.routes.js`

**Success Criteria:**
- [ ] Endpoints work and return validation results
- [ ] Validation results are persisted to database
- [ ] Can validate single or all rules

---

### 4.3 Frontend - Rule Validation UI (3 hours)

**Tasks:**
- [ ] Enhance `public/admin/rule-editor.html` - Add Validation Panel
  - [ ] Add "Validate" tab in right panel
    - [ ] "Run Validation" button
    - [ ] Validation results display:
      - [ ] Overall status: ✅ PASSED | ⚠️ WARNINGS | ❌ FAILED
      - [ ] Test results (expandable sections):
        - [ ] ✅ Classification Test
          - [ ] Expected vs Actual quadrant/persistence
          - [ ] Parameters extracted
        - [ ] ✅ Parameter Extraction Test
          - [ ] List of extracted parameters
        - [ ] ✅ Conflict Detection Test
          - [ ] No conflicts found / List conflicts
        - [ ] ✅ Boundary Check
          - [ ] Allowed / Blocked (reason)
      - [ ] Warnings (if any)
      - [ ] Errors (if any)
      - [ ] Overall score: 95/100
    - [ ] "Fix Issues" button (if failures)
      - [ ] Opens AI optimizer with context

- [ ] Create `public/admin/rule-validator.html` (standalone page)
  - [ ] Bulk validation interface
  - [ ] "Validate All Rules" button
  - [ ] Progress bar during validation
  - [ ] Results table:
    - [ ] Rule ID | Rule Text | Status | Score | Actions
    - [ ] Filter: Show All | Passed | Failed | Warnings
    - [ ] Can click rule to see details
  - [ ] Summary statistics:
    - [ ] Total rules validated
    - [ ] Passed: X (%)
    - [ ] Failed: Y (%)
    - [ ] Average score

- [ ] Create `public/js/admin/rule-validator-ui.js`
  - [ ] Handle single rule validation
    - [ ] Call API
    - [ ] Display results in editor panel
    - [ ] Highlight issues in rule text
  - [ ] Handle bulk validation
    - [ ] Call API with progress tracking
    - [ ] Render results table
    - [ ] Update statistics
  - [ ] Interactive result exploration
    - [ ] Click to expand test details
    - [ ] Show diff for classification mismatches
    - [ ] Link to conflicting rules

**Files Modified:**
- `public/admin/rule-editor.html`

**Files Created:**
- `public/admin/rule-validator.html`
- `public/js/admin/rule-validator-ui.js`

**Success Criteria:**
- [ ] Can validate rules from editor
- [ ] Validation results are clear and actionable
- [ ] Bulk validation works efficiently
- [ ] Failed rules are easy to identify and fix

---

### 4.4 Integration Tests for Validator (2 hours)

**Tasks:**
- [ ] Create `tests/integration/rule-validator.test.js`
  - [ ] Test classification accuracy
    - [ ] Create rule with known quadrant
    - [ ] Validate
    - [ ] Verify classification matches
  - [ ] Test parameter extraction
    - [ ] Create rule with variables
    - [ ] Validate
    - [ ] Verify parameters extracted
  - [ ] Test conflict detection
    - [ ] Create two conflicting rules
    - [ ] Validate second rule
    - [ ] Verify conflict detected
  - [ ] Test boundary enforcement
    - [ ] Create rule about values decision
    - [ ] Validate
    - [ ] Verify boundary violation detected
  - [ ] Test validation persistence
    - [ ] Validate rule
    - [ ] Check DB for validation results
    - [ ] Verify validationStatus updated

**Files Created:**
- `tests/integration/rule-validator.test.js`

**Success Criteria:**
- [ ] All validation tests pass
- [ ] Validator correctly identifies issues
- [ ] Results are persisted

---

### 4.5 Testing & Polish (1 hour)

**Tasks:**
- [ ] Manual testing
  - [ ] Validate a well-formed rule (should pass)
  - [ ] Validate a poorly-formed rule (should fail)
  - [ ] Create conflicting rules and validate
  - [ ] Run bulk validation on all rules
- [ ] Edge cases
  - [ ] Rule with no parameters
  - [ ] Rule with undefined variables
  - [ ] Rule that violates boundaries
- [ ] Performance testing
  - [ ] Validate 100 rules - should complete in reasonable time
- [ ] UI polish
  - [ ] Loading states during validation
  - [ ] Clear error messages
  - [ ] Success animations

**Success Criteria:**
- [ ] Validation is reliable and accurate
- [ ] No performance issues
- [ ] UI is polished and intuitive

---

## **PHASE 5: Project Templates & Cloning** (6-8 hours)

**Goal:** Rapid project creation via templates and cloning

### 5.1 Backend - Template Model & Service (2 hours)

**Tasks:**
- [ ] Create `src/models/Template.model.js`
  - [ ] Schema (as shown in Database Schema section)
  - [ ] Static methods:
    - [ ] `findByCategory(category)`
    - [ ] `findPopular()` (most used)

- [ ] Create `src/services/TemplateManager.service.js`
  - [ ] `createProjectFromTemplate(templateId, projectData)` → creates project
    - [ ] Fetch template
    - [ ] Merge template defaults with user overrides
    - [ ] Create project in database
    - [ ] Link universal rules
    - [ ] Add template-suggested rules
    - [ ] Return created project
  - [ ] `cloneProject(sourceProjectId, newProjectData)` → clones existing project
    - [ ] Fetch source project
    - [ ] Copy configuration
    - [ ] Copy custom rules
    - [ ] Apply variable overrides
    - [ ] Create new project
    - [ ] Return created project

**Files Created:**
- `src/models/Template.model.js`
- `src/services/TemplateManager.service.js`

**Success Criteria:**
- [ ] Can create projects from templates
- [ ] Can clone existing projects
- [ ] New projects have correct rules and variables

---

### 5.2 Backend - Template & Cloning API (1 hour)

**Tasks:**
- [ ] Create `src/controllers/templates.controller.js`
  - [ ] `GET /api/admin/templates` - List all templates
  - [ ] `GET /api/admin/templates/:id` - Get template details
  - [ ] `POST /api/admin/projects/from-template` - Create from template
    - [ ] Body: `{ templateId, projectName, variables: {...} }`
  - [ ] `POST /api/admin/projects/:id/clone` - Clone project
    - [ ] Body: `{ newProjectName, variableOverrides: {...} }`

- [ ] Create `src/routes/templates.routes.js`

**Files Created:**
- `src/controllers/templates.controller.js`
- `src/routes/templates.routes.js`

**Files Modified:**
- `src/routes/index.js`

**Success Criteria:**
- [ ] Endpoints work and create projects
- [ ] Template-based creation applies defaults
- [ ] Cloning preserves configuration

---

### 5.3 Backend - Seed Templates (1 hour)

**Tasks:**
- [ ] Create `scripts/seed-templates.js`
  - [ ] Create "Node.js + Express + MongoDB" template
    - [ ] Matches Tractatus stack
    - [ ] Links 12 universal rules
    - [ ] Includes Node.js-specific suggested rules
  - [ ] Create "React + Firebase" template (for future)
  - [ ] Create "Python + FastAPI + PostgreSQL" template (for future)

- [ ] Run seed script
  - [ ] Verify templates created
  - [ ] Test creating project from template

**Files Created:**
- `scripts/seed-templates.js`

**Success Criteria:**
- [ ] Templates exist in database
- [ ] Can create project from template successfully

---

### 5.4 Frontend - New Project Wizard (2.5 hours)

**Tasks:**
- [ ] Create `public/admin/project-wizard.html` (modal/multi-step form)
  - [ ] **Step 1: Choose Source**
    - [ ] Radio buttons:
      - [ ] 📋 From Template
      - [ ] 📑 Clone Existing Project
      - [ ] ✨ Start from Scratch
  - [ ] **Step 2a: Select Template** (if "From Template")
    - [ ] Grid of template cards
    - [ ] Each shows: Name, Description, Tech stack, Rule count
    - [ ] Click to select
  - [ ] **Step 2b: Select Project** (if "Clone")
    - [ ] Dropdown of existing projects
  - [ ] **Step 3: Project Details**
    - [ ] Project Name (required)
    - [ ] Project Slug (auto-generated from name, editable)
    - [ ] Description
    - [ ] Production Domain
  - [ ] **Step 4: Infrastructure** (pre-filled from template/source)
    - [ ] VPS Host
    - [ ] Database Type & Port
    - [ ] SSH User & Key
    - [ ] Deploy Path
    - [ ] All editable
  - [ ] **Step 5: Variables** (pre-filled, can override)
    - [ ] List of variables from template
    - [ ] Can edit values
    - [ ] Preview how rules will look with these values
  - [ ] **Step 6: Review & Create**
    - [ ] Summary:
      - [ ] Project details
      - [ ] X universal rules will be inherited
      - [ ] Y template rules will be added
      - [ ] Infrastructure summary
    - [ ] "Create Project" button

- [ ] Create `public/js/admin/project-wizard.js`
  - [ ] Multi-step form navigation
  - [ ] Load templates from API
  - [ ] Load projects for cloning
  - [ ] Auto-generate slug from name
  - [ ] Variable preview/interpolation
  - [ ] Submit to API
    - [ ] `/api/admin/projects/from-template` or
    - [ ] `/api/admin/projects/:id/clone` or
    - [ ] `/api/admin/projects` (from scratch)
  - [ ] Show progress/success
  - [ ] Redirect to new project config on success

**Files Created:**
- `public/admin/project-wizard.html`
- `public/js/admin/project-wizard.js`

**Success Criteria:**
- [ ] Wizard guides user through project creation
- [ ] Can create from template
- [ ] Can clone existing project
- [ ] Can start from scratch
- [ ] Preview shows interpolated rules
- [ ] Successfully creates project

---

### 5.5 Frontend - Template Library Page (Optional) (1 hour)

**Tasks:**
- [ ] Create `public/admin/project-templates.html`
  - [ ] Browse all templates
  - [ ] Filter by category
  - [ ] View template details
  - [ ] "Use Template" button → opens wizard

- [ ] Create `public/js/admin/template-selector.js`
  - [ ] Fetch templates
  - [ ] Render cards
  - [ ] Filter logic
  - [ ] Launch wizard with pre-selected template

**Files Created:**
- `public/admin/project-templates.html`
- `public/js/admin/template-selector.js`

**Success Criteria:**
- [ ] Easy to browse templates
- [ ] Can launch wizard from template page

---

### 5.6 Testing & Validation (0.5 hour)

**Tasks:**
- [ ] Test template creation
  - [ ] Create project from "Node.js + Express + MongoDB" template
  - [ ] Verify all defaults applied
  - [ ] Verify rules linked correctly
- [ ] Test cloning
  - [ ] Clone Tractatus project
  - [ ] Change variables
  - [ ] Verify rules interpolated with new variables
- [ ] Test from-scratch
  - [ ] Create project without template
  - [ ] Verify basic setup works
- [ ] Edge cases
  - [ ] Template with missing rules
  - [ ] Cloning non-existent project
  - [ ] Invalid variable names

**Success Criteria:**
- [ ] All creation methods work
- [ ] Projects are correctly configured
- [ ] No data corruption

---

## **PHASE 6: Polish, Documentation & Deployment** (4-6 hours)

**Goal:** Production-ready system with documentation

### 6.1 UI/UX Polish (2 hours)

**Tasks:**
- [ ] **Consistent Styling**
  - [ ] Ensure all pages use same Tailwind theme
  - [ ] Consistent button styles
  - [ ] Consistent form styles
  - [ ] Consistent card/panel styles
- [ ] **Responsive Design**
  - [ ] Test all pages on mobile (320px+)
  - [ ] Test on tablet (768px+)
  - [ ] Adjust layouts for small screens
- [ ] **Loading States**
  - [ ] Spinners for API calls
  - [ ] Skeleton loaders for lists
  - [ ] Progress bars for long operations
- [ ] **Error Handling**
  - [ ] Toast notifications for errors
  - [ ] Inline validation messages
  - [ ] Clear error states
- [ ] **Accessibility**
  - [ ] Keyboard navigation
  - [ ] ARIA labels
  - [ ] Focus management
  - [ ] Color contrast (WCAG AA)
- [ ] **Animations**
  - [ ] Smooth transitions
  - [ ] Success animations (checkmarks, etc.)
  - [ ] Micro-interactions

**Success Criteria:**
- [ ] Professional, polished appearance
- [ ] Works on all screen sizes
- [ ] Accessible to all users
- [ ] Smooth, delightful interactions

---

### 6.2 Documentation (2 hours)

**Tasks:**
- [ ] Create `docs/API_REFERENCE.md`
  - [ ] Document all API endpoints
  - [ ] Request/response examples
  - [ ] Error codes
- [ ] Create `docs/RULE_OPTIMIZATION_GUIDE.md`
  - [ ] How clarity scoring works
  - [ ] How to write high-quality rules
  - [ ] Best practices
- [ ] Create `docs/PROJECT_TEMPLATES_GUIDE.md`
  - [ ] How to create custom templates
  - [ ] Template schema reference
- [ ] Create `docs/USER_GUIDE.md`
  - [ ] Getting started
  - [ ] Managing rules
  - [ ] Managing projects
  - [ ] CLAUDE.md migration
  - [ ] Screenshots/videos
- [ ] Update `README.md`
  - [ ] Feature overview
  - [ ] Installation instructions
  - [ ] Quick start guide
  - [ ] Link to full documentation
- [ ] Code comments
  - [ ] Add JSDoc comments to all public functions
  - [ ] Explain complex algorithms

**Files Created:**
- `docs/API_REFERENCE.md`
- `docs/RULE_OPTIMIZATION_GUIDE.md`
- `docs/PROJECT_TEMPLATES_GUIDE.md`
- `docs/USER_GUIDE.md`

**Files Modified:**
- `README.md`

**Success Criteria:**
- [ ] Comprehensive documentation
- [ ] Easy to understand
- [ ] Code is well-commented

---

### 6.3 Security Audit (1 hour)

**Tasks:**
- [ ] **Authentication**
  - [ ] Verify all admin endpoints require auth
  - [ ] Check for auth bypasses
- [ ] **Input Validation**
  - [ ] Verify all user inputs are validated
  - [ ] Check for SQL injection (N/A for MongoDB, but check NoSQL injection)
  - [ ] Check for XSS vulnerabilities
- [ ] **CORS**
  - [ ] Verify CORS is properly configured
- [ ] **Environment Variables**
  - [ ] Ensure sensitive data in .env, not codebase
  - [ ] Check .env.example is up to date
- [ ] **Rate Limiting**
  - [ ] Add rate limiting to API endpoints
- [ ] **HTTPS**
  - [ ] Ensure production uses HTTPS
  - [ ] No mixed content warnings

**Success Criteria:**
- [ ] No security vulnerabilities found
- [ ] All sensitive data protected
- [ ] Production-ready security posture

---

### 6.4 Performance Optimization (0.5 hour)

**Tasks:**
- [ ] **Database**
  - [ ] Verify all necessary indexes exist
  - [ ] Check slow queries
- [ ] **Frontend**
  - [ ] Minify JavaScript
  - [ ] Compress images
  - [ ] Lazy load large lists
- [ ] **API**
  - [ ] Add caching where appropriate
  - [ ] Optimize N+1 queries

**Success Criteria:**
- [ ] Pages load quickly
- [ ] No performance bottlenecks
- [ ] Database queries are optimized

---

### 6.5 Deployment (0.5 hour)

**Tasks:**
- [ ] **Database Migration**
  - [ ] Run all migration scripts on production DB
  - [ ] Verify data integrity
- [ ] **Deploy Code**
  - [ ] Push to production server
  - [ ] Restart services
- [ ] **Smoke Tests**
  - [ ] Login works
  - [ ] Can view rules
  - [ ] Can create rule
  - [ ] Can switch projects
  - [ ] No console errors
- [ ] **Monitoring**
  - [ ] Set up error monitoring (Sentry, etc.)
  - [ ] Set up uptime monitoring

**Success Criteria:**
- [ ] System deployed to production
- [ ] All features work in production
- [ ] Monitoring is active

---

## 📊 Summary

### Total Estimated Time: **46-58 hours**

| Phase | Estimated Time | Key Deliverables |
|-------|----------------|------------------|
| Phase 1: Core Rule Manager | 8-10 hours | Rule CRUD, dashboard, editor |
| Phase 2: AI Optimizer | 10-12 hours | Rule optimization, CLAUDE.md migration |
| Phase 3: Multi-Project | 10-12 hours | Project management, variable interpolation |
| Phase 4: Validation Engine | 8-10 hours | Real-time rule validation |
| Phase 5: Templates & Cloning | 6-8 hours | Project templates, cloning |
| Phase 6: Polish & Deployment | 4-6 hours | Documentation, security, deployment |

### Milestones

**Milestone 1** (After Phase 1): Basic rule management working
**Milestone 2** (After Phase 2): AI-powered optimization and CLAUDE.md migration
**Milestone 3** (After Phase 3): Multi-project system operational
**Milestone 4** (After Phase 4): Validation engine integrated
**Milestone 5** (After Phase 5): Template system complete
**Milestone 6** (After Phase 6): **Production-ready, world-class system**

---

## 🎯 Success Criteria

**Product is ready when:**

- [ ] All 18+ rules managed via UI
- [ ] CLAUDE.md successfully migrated to rules
- [ ] Can manage multiple projects (Tractatus + others)
- [ ] Rules validated against framework in real-time
- [ ] Can create projects from templates in <2 minutes
- [ ] AI optimizer improves rule clarity measurably
- [ ] Documentation is comprehensive
- [ ] No security vulnerabilities
- [ ] Deployed to production and stable

**Commercialization Ready When:**

- [ ] System is polished and professional
- [ ] Documentation suitable for external users
- [ ] Multi-tenant support (user authentication/authorization)
- [ ] Pricing/billing system (if SaaS)
- [ ] Marketing materials prepared
- [ ] Support system in place

---

## 🚦 Next Steps

**Immediate Actions:**

1. **Review this plan** - Confirm approach and priorities
2. **Fix MongoDB persistence issues** - Resolve 3 failing integration tests (quick win)
3. **Begin Phase 1** - Start with backend rule model enhancements
4. **Set up task tracking** - Use todo list to track granular progress

**Questions to Resolve:**

1. Should we proceed with all phases, or focus on subset first?
2. Any features to add/remove/modify?
3. Priority order - does this sequence make sense?
4. Timeline - is this realistic for your schedule?

---

Ready to start building? 🚀