2298d36bed
- 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>
2540 lines
80 KiB
Markdown
2540 lines
80 KiB
Markdown
# 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? 🚀
|