TheFlow 2298d36bed fix(submissions): restructure Economist package and fix article display

- Create Economist SubmissionTracking package correctly:
  * mainArticle = full blog post content
  * coverLetter = 216-word SIR— letter
  * Links to blog post via blogPostId
- Archive 'Letter to The Economist' from blog posts (it's the cover letter)
- Fix date display on article cards (use published_at)
- Target publication already displaying via blue badge

Database changes:
- Make blogPostId optional in SubmissionTracking model
- Economist package ID: 68fa85ae49d4900e7f2ecd83
- Le Monde package ID: 68fa2abd2e6acd5691932150

Next: Enhanced modal with tabs, validation, export

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-24 08:47:42 +13:00

80 KiB

Raw Blame History

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:

Replaces fragile CLAUDE.md with validated, optimized governance rules
Enables multi-project management across portfolio with variable substitution
Provides AI-assisted rule optimization for clarity and effectiveness
Offers project templates for instant deployment to new projects
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

{
  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

{
  _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)

{
  _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

{
  _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)

{
  _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)

{
  _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)

{
  _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)

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:

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:

{
  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:

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). 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
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:
```
{
  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:

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

Questions to Resolve:

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

Ready to start building? 🚀

80 KiB Raw Blame History

Multi-Project Governance System - Implementation Plan

🎯 Executive Summary

📐 System Architecture

Three-Tier Rule System

Core Components

🗂️ Database Schema

Enhanced governanceRules Collection

NEW projects Collection

NEW projectRules Collection (Overrides)

NEW templates Collection

NEW sessions Collection (Concurrent Session Support)

NEW sessionState Collection (Session-Specific State)

NEW tokenCheckpoints Collection (Session Milestones)

📁 File Structure

🚀 Implementation Phases

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

1.1 Backend - Enhanced Rule Model (1 hour)

1.2 Backend - Rule Management API (2 hours)

1.3 Frontend - Rule Manager Dashboard (3 hours)

1.4 Frontend - Rule Editor Modal (2.5 hours)

1.5 Testing & Polish (1.5 hours)

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

2.1 Backend - Rule Optimizer Service (3 hours)

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

2.3 Backend - API Endpoints for Optimization (1 hour)

2.4 Frontend - AI Optimization UI (3 hours)

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

2.6 Testing & Validation (1 hour)

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

3.1 Backend - Project Model & API (3 hours)

3.2 Backend - Rule Interpolator Service (2 hours)

3.3 Backend - Seed Initial Projects (1 hour)

3.4 Frontend - Project Switcher (1 hour)

3.5 Frontend - Project Manager Dashboard (2.5 hours)

3.6 Frontend - Project Configuration Editor (2.5 hours)

3.7 Testing & Integration (1 hour)

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

3.5.1 Backend - Session Models (1 hour)

3.5.2 Backend - Session Management Service (1.5 hours)

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

3.5.4 Framework Integration - Update Core Services (1 hour)

3.5.5 Testing - Concurrent Session Tests (0.5 hour)

3.5.6 Documentation & Migration Guide (0.5 hour)

3.5.7 Testing & Validation (0.5 hour)

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

4.1 Backend - Rule Validator Service (4 hours)

4.2 Backend - Validation API Endpoints (1 hour)

4.3 Frontend - Rule Validation UI (3 hours)

4.4 Integration Tests for Validator (2 hours)

4.5 Testing & Polish (1 hour)

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

5.1 Backend - Template Model & Service (2 hours)

5.2 Backend - Template & Cloning API (1 hour)

5.3 Backend - Seed Templates (1 hour)

5.4 Frontend - New Project Wizard (2.5 hours)

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

5.6 Testing & Validation (0.5 hour)

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

6.1 UI/UX Polish (2 hours)

6.2 Documentation (2 hours)

6.3 Security Audit (1 hour)

6.4 Performance Optimization (0.5 hour)

6.5 Deployment (0.5 hour)

📊 Summary

Total Estimated Time: 46-58 hours

Milestones

🎯 Success Criteria

🚦 Next Steps

80 KiB

Raw Blame History

Enhanced `governanceRules` Collection

NEW `projects` Collection

NEW `projectRules` Collection (Overrides)

NEW `templates` Collection

NEW `sessions` Collection (Concurrent Session Support)

NEW `sessionState` Collection (Session-Specific State)

NEW `tokenCheckpoints` Collection (Session Milestones)