ruvnet-kb-first 5.0.0 → 6.0.0

package/src/mcp-server.js

@@ -1,364 +1,712 @@
 /**
- * RuvNet KB-First MCP Server
+ * RuvNet KB-First MCP Server - Score-Driven Architecture
+ * Version 6.0.0
  *
- * Model Context Protocol server for Claude Code integration.
- * Provides KB-First tools directly within Claude Code.
+ * PHILOSOPHY: Scoring IS the enforcement mechanism.
+ * - Every operation requires baseline score first
+ * - Every operation shows delta (before/after)
+ * - Hard gates BLOCK on negative deltas
+ * - No shortcuts - rigorous measurement drives quality
+ *
+ * 4 Tools (not 7):
+ *   1. kb_first_assess  - Calculate baseline scores (KB + App + Process)
+ *   2. kb_first_phase   - Execute phase work with delta tracking
+ *   3. kb_first_delta   - Explicit before/after comparison
+ *   4. kb_first_gate    - Hard gate that blocks on negative delta
  *
  * Usage:
  *   npx ruvnet-kb-first mcp
  *   node src/mcp-server.js
  */
 
-import { createServer } from 'http';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
+import { globSync } from 'glob';
 
 // MCP Protocol Constants
 const MCP_VERSION = '0.1.0';
 const SERVER_NAME = 'ruvnet-kb-first';
-const SERVER_VERSION = '5.0.0';
+const SERVER_VERSION = '6.0.0';
 
 /**
- * Available MCP Tools
+ * Score Categories (total 100 points)
+ * These are the ONLY metrics that matter
  */
-const TOOLS = [
-  {
-    name: 'kb_first_init',
-    description: 'Initialize KB-First structure in the current project',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        force: {
-          type: 'boolean',
-          description: 'Overwrite existing configuration'
-        },
-        template: {
-          type: 'string',
-          enum: ['basic', 'api', 'fullstack'],
-          description: 'Project template type'
-        }
-      }
+const SCORE_WEIGHTS = {
+  kb: {
+    weight: 40,
+    components: {
+      entries: 10,        // KB has content
+      coverage: 10,       // Domain coverage completeness
+      embeddings: 10,     // Vectors generated
+      freshness: 10       // Recent updates
     }
   },
-  {
-    name: 'kb_first_score',
-    description: 'Calculate KB-First compliance score for the project',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        detailed: {
-          type: 'boolean',
-          description: 'Show detailed breakdown'
-        }
-      }
+  app: {
+    weight: 40,
+    components: {
+      kbCitations: 15,    // Code files cite KB sources
+      gapResolution: 10,  // Gaps identified and resolved
+      testCoverage: 10,   // Tests exist and pass
+      security: 5         // Security basics in place
     }
   },
+  process: {
+    weight: 20,
+    components: {
+      phaseCompletion: 10, // Phases properly completed
+      gatesPassed: 5,      // Hard gates verified
+      documentation: 5     // Docs exist
+    }
+  }
+};
+
+/**
+ * Phase definitions
+ */
+const PHASES = {
+  0:    { name: 'Assessment', gate: 'assessment_documented' },
+  1:    { name: 'KB Design', gate: 'schema_designed' },
+  1.5:  { name: 'Hooks Setup', gate: 'hooks_verified' },
+  2:    { name: 'Schema Definition', gate: 'schema_created' },
+  3:    { name: 'KB Population', gate: 'kb_score_50' },
+  4:    { name: 'Scoring & Gaps', gate: 'kb_score_80' },
+  5:    { name: 'Integration', gate: 'integration_tested' },
+  6:    { name: 'Testing', gate: 'tests_passing' },
+  7:    { name: 'Optimization', gate: 'performance_met' },
+  7.5:  { name: 'Testing Gate', gate: 'coverage_80' },
+  8:    { name: 'Verification', gate: 'all_checks_pass' },
+  9:    { name: 'Security', gate: 'security_audit_passed' },
+  10:   { name: 'Documentation', gate: 'docs_complete' },
+  11:   { name: 'Deployment', gate: 'deployed' },
+  11.5: { name: 'Observability', gate: 'monitoring_active' },
+  12:   { name: 'KB Operations', gate: 'operations_ready' }
+};
+
+/**
+ * MCP Tools - Score-Driven Architecture
+ */
+const TOOLS = [
   {
-    name: 'kb_first_verify',
-    description: 'Run KB-First verification checks',
+    name: 'kb_first_assess',
+    description: `Calculate comprehensive baseline scores for KB, App, and Process.
+ALWAYS RUN THIS FIRST before any work. Returns:
+- KB Score (40 points): entries, coverage, embeddings, freshness
+- App Score (40 points): citations, gap resolution, tests, security
+- Process Score (20 points): phases, gates, documentation
+- Total (100 points)
+
+This becomes your BASELINE for delta comparison.`,
     inputSchema: {
       type: 'object',
       properties: {
-        phase: {
-          type: 'number',
-          description: 'Verify specific phase (0-11)'
-        },
-        all: {
-          type: 'boolean',
-          description: 'Run all verification scripts'
-        }
+        detailed: { type: 'boolean', description: 'Show component breakdown', default: true },
+        saveBaseline: { type: 'boolean', description: 'Save as baseline for delta comparison', default: true }
       }
     }
   },
   {
-    name: 'kb_first_status',
-    description: 'Show KB-First project status',
+    name: 'kb_first_phase',
+    description: `Execute a phase with automatic delta tracking.
+REQUIRES: kb_first_assess must be run first to establish baseline.
+
+Workflow:
+1. Loads baseline score from last kb_first_assess
+2. Shows phase requirements and sub-phases
+3. Returns guidance for completing the phase
+4. REMINDS you to run kb_first_delta when done
+
+Will WARN if baseline is stale (>1 hour old).`,
     inputSchema: {
       type: 'object',
       properties: {
-        detailed: {
-          type: 'boolean',
-          description: 'Show detailed status'
-        }
-      }
+        phase: { type: 'number', description: 'Phase number (0-12, including 1.5, 7.5, 11.5)' }
+      },
+      required: ['phase']
     }
   },
   {
-    name: 'kb_first_phase',
-    description: 'Get information about a specific build phase',
+    name: 'kb_first_delta',
+    description: `Compare current scores against baseline. THE ENFORCEMENT MECHANISM.
+Shows:
+- Baseline score (from kb_first_assess)
+- Current score (calculated now)
+- Delta (+ improvement or - regression)
+- VERDICT: PASS (positive delta) or FAIL (negative delta)
+
+If delta is negative, you CANNOT proceed to next phase.
+This prevents shortcuts and enforces rigor.`,
     inputSchema: {
       type: 'object',
       properties: {
-        phase: {
-          type: 'number',
-          description: 'Phase number (0, 1, 1.5, 2-11)'
-        }
-      },
-      required: ['phase']
+        showBreakdown: { type: 'boolean', description: 'Show which components changed', default: true }
+      }
     }
   },
   {
-    name: 'kb_first_hooks',
-    description: 'Manage KB-First hooks',
+    name: 'kb_first_gate',
+    description: `Hard gate check for phase transition.
+BLOCKS progress if:
+- Delta is negative (score dropped)
+- Required gate condition not met
+- Baseline not established
+
+Returns:
+- canProceed: boolean
+- blockReason: string (if blocked)
+- nextPhase: number (if can proceed)
+
+THIS IS THE HARD GATE. No bypassing.`,
     inputSchema: {
       type: 'object',
       properties: {
-        action: {
-          type: 'string',
-          enum: ['install', 'verify', 'train', 'status'],
-          description: 'Hook action to perform'
-        }
+        phase: { type: 'number', description: 'Phase to verify gate for' }
       },
-      required: ['action']
+      required: ['phase']
     }
   }
 ];
 
 /**
- * Handle MCP tool calls
+ * Calculate all scores
  */
-async function handleToolCall(toolName, args) {
-  const cwd = process.cwd();
-
-  switch (toolName) {
-    case 'kb_first_init':
-      return await handleInit(cwd, args);
-
-    case 'kb_first_score':
-      return await handleScore(cwd, args);
-
-    case 'kb_first_verify':
-      return await handleVerify(cwd, args);
+function calculateScores(cwd) {
+  const scores = {
+    kb: { total: 0, max: 40, components: {} },
+    app: { total: 0, max: 40, components: {} },
+    process: { total: 0, max: 20, components: {} },
+    total: 0,
+    max: 100,
+    grade: 'F',
+    timestamp: new Date().toISOString()
+  };
 
-    case 'kb_first_status':
-      return await handleStatus(cwd, args);
+  // ===== KB SCORE (40 points) =====
+  const ruvectorDir = join(cwd, '.ruvector');
+  const kbDir = join(cwd, 'src', 'kb');
+
+  // KB Entries (10 points)
+  let kbEntries = 0;
+  if (existsSync(kbDir)) {
+    try {
+      const files = readdirSync(kbDir);
+      kbEntries = files.length;
+    } catch {}
+  }
+  scores.kb.components.entries = Math.min(10, Math.floor(kbEntries / 5) * 2);
+
+  // KB Coverage (10 points) - based on documented domains
+  const docsDir = join(cwd, 'docs');
+  let domainDocs = 0;
+  if (existsSync(docsDir)) {
+    try {
+      const files = readdirSync(docsDir);
+      domainDocs = files.filter(f => f.endsWith('.md')).length;
+    } catch {}
+  }
+  scores.kb.components.coverage = Math.min(10, domainDocs * 2);
+
+  // KB Embeddings (10 points) - check for vector files or config
+  const configPath = join(ruvectorDir, 'config.json');
+  let hasEmbeddings = false;
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      hasEmbeddings = config.kbFirst?.embeddings === true || kbEntries > 0;
+    } catch {}
+  }
+  scores.kb.components.embeddings = hasEmbeddings ? 10 : 0;
+
+  // KB Freshness (10 points) - recent updates
+  let freshness = 0;
+  if (existsSync(ruvectorDir)) {
+    try {
+      const stat = statSync(ruvectorDir);
+      const daysSinceUpdate = (Date.now() - stat.mtime.getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSinceUpdate < 1) freshness = 10;
+      else if (daysSinceUpdate < 7) freshness = 7;
+      else if (daysSinceUpdate < 30) freshness = 4;
+      else freshness = 0;
+    } catch {}
+  }
+  scores.kb.components.freshness = freshness;
+
+  scores.kb.total = Object.values(scores.kb.components).reduce((a, b) => a + b, 0);
+
+  // ===== APP SCORE (40 points) =====
+  const srcDir = join(cwd, 'src');
+
+  // KB Citations (15 points)
+  let codeFiles = [];
+  let filesWithCitation = 0;
+  if (existsSync(srcDir)) {
+    try {
+      codeFiles = globSync('**/*.{ts,tsx,js,jsx,py,go,rs}', { cwd: srcDir });
+      for (const file of codeFiles) {
+        try {
+          const content = readFileSync(join(srcDir, file), 'utf-8');
+          if (content.includes('KB-Generated:') || content.includes('Sources:') || content.includes('@kb-source')) {
+            filesWithCitation++;
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  const citationPercent = codeFiles.length > 0 ? filesWithCitation / codeFiles.length : 1;
+  scores.app.components.kbCitations = Math.round(citationPercent * 15);
+
+  // Gap Resolution (10 points)
+  const gapsPath = join(ruvectorDir, 'gaps.jsonl');
+  let gapCount = 0;
+  if (existsSync(gapsPath)) {
+    try {
+      const content = readFileSync(gapsPath, 'utf-8').trim();
+      gapCount = content ? content.split('\n').length : 0;
+    } catch {}
+  }
+  scores.app.components.gapResolution = Math.max(0, 10 - gapCount);
+
+  // Test Coverage (10 points)
+  let hasTests = false;
+  const testDirs = ['tests', 'test', '__tests__', 'src/__tests__'];
+  for (const td of testDirs) {
+    if (existsSync(join(cwd, td))) {
+      hasTests = true;
+      break;
+    }
+  }
+  const testFiles = existsSync(srcDir) ? globSync('**/*.{test,spec}.{ts,tsx,js,jsx}', { cwd: srcDir }) : [];
+  scores.app.components.testCoverage = hasTests ? 5 : 0;
+  scores.app.components.testCoverage += Math.min(5, testFiles.length);
+
+  // Security (5 points)
+  let secScore = 5;
+  const gitignorePath = join(cwd, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    try {
+      const content = readFileSync(gitignorePath, 'utf-8');
+      if (!content.includes('.env')) secScore -= 2;
+      if (!content.includes('node_modules')) secScore -= 1;
+    } catch {}
+  } else {
+    secScore -= 3;
+  }
+  scores.app.components.security = Math.max(0, secScore);
 
-    case 'kb_first_phase':
-      return await handlePhase(cwd, args);
+  scores.app.total = Object.values(scores.app.components).reduce((a, b) => a + b, 0);
 
-    case 'kb_first_hooks':
-      return await handleHooks(cwd, args);
+  // ===== PROCESS SCORE (20 points) =====
 
-    default:
-      return {
-        error: `Unknown tool: ${toolName}`
-      };
+  // Phase Completion (10 points)
+  let completedPhases = [];
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      completedPhases = config.phases?.completed || [];
+    } catch {}
   }
+  const totalPhases = Object.keys(PHASES).length;
+  scores.process.components.phaseCompletion = Math.round((completedPhases.length / totalPhases) * 10);
+
+  // Gates Passed (5 points)
+  let gatesPassed = 0;
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      gatesPassed = Object.values(config.phases?.gates || {}).filter(v => v === true).length;
+    } catch {}
+  }
+  scores.process.components.gatesPassed = Math.min(5, Math.round((gatesPassed / totalPhases) * 5));
+
+  // Documentation (5 points)
+  let docScore = 0;
+  if (existsSync(join(cwd, 'README.md'))) docScore += 2;
+  if (existsSync(join(cwd, 'docs', 'api.md')) || existsSync(join(cwd, 'docs', 'API.md'))) docScore += 1;
+  if (existsSync(join(cwd, 'docs', 'architecture.md'))) docScore += 1;
+  if (existsSync(join(cwd, 'CHANGELOG.md'))) docScore += 1;
+  scores.process.components.documentation = Math.min(5, docScore);
+
+  scores.process.total = Object.values(scores.process.components).reduce((a, b) => a + b, 0);
+
+  // ===== TOTAL =====
+  scores.total = scores.kb.total + scores.app.total + scores.process.total;
+
+  // Grade
+  if (scores.total >= 98) scores.grade = 'A+';
+  else if (scores.total >= 93) scores.grade = 'A';
+  else if (scores.total >= 90) scores.grade = 'A-';
+  else if (scores.total >= 87) scores.grade = 'B+';
+  else if (scores.total >= 83) scores.grade = 'B';
+  else if (scores.total >= 80) scores.grade = 'B-';
+  else if (scores.total >= 70) scores.grade = 'C';
+  else if (scores.total >= 60) scores.grade = 'D';
+  else scores.grade = 'F';
+
+  return scores;
 }
 
-async function handleInit(cwd, args) {
-  const { initCommand } = await import('./commands/init.js');
-
-  // Run init (capture output)
-  const configPath = join(cwd, '.ruvector', 'config.json');
-  const wasInitialized = existsSync(configPath);
+/**
+ * Tool Handlers
+ */
+async function handleKbFirstAssess(cwd, args) {
+  const scores = calculateScores(cwd);
+
+  // Save baseline
+  if (args.saveBaseline !== false) {
+    const ruvectorDir = join(cwd, '.ruvector');
+    if (!existsSync(ruvectorDir)) {
+      mkdirSync(ruvectorDir, { recursive: true });
+    }
+    writeFileSync(join(ruvectorDir, 'baseline.json'), JSON.stringify(scores, null, 2));
+  }
 
-  try {
-    await initCommand({
-      force: args.force || false,
-      template: args.template || 'basic',
-      hooks: true
-    });
+  const result = {
+    action: 'BASELINE_ESTABLISHED',
+    timestamp: scores.timestamp,
+    total: scores.total,
+    max: scores.max,
+    grade: scores.grade,
+    summary: {
+      kb: `${scores.kb.total}/${scores.kb.max}`,
+      app: `${scores.app.total}/${scores.app.max}`,
+      process: `${scores.process.total}/${scores.process.max}`
+    },
+    nextStep: 'Run kb_first_phase to begin work, then kb_first_delta to measure improvement'
+  };
 
-    return {
-      success: true,
-      message: wasInitialized && !args.force
-        ? 'Project already initialized'
-        : 'KB-First project initialized successfully',
-      configPath
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error.message
+  if (args.detailed !== false) {
+    result.breakdown = {
+      kb: scores.kb.components,
+      app: scores.app.components,
+      process: scores.process.components
     };
   }
+
+  return result;
 }
 
-async function handleScore(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+async function handleKbFirstPhase(cwd, args) {
+  const phase = args.phase;
+  const phaseInfo = PHASES[phase];
 
-  if (!existsSync(configPath)) {
+  if (!phaseInfo) {
     return {
-      success: false,
-      error: 'Not a KB-First project. Run kb_first_init first.'
+      error: `Unknown phase: ${phase}`,
+      validPhases: Object.entries(PHASES).map(([k, v]) => ({ phase: parseFloat(k), name: v.name }))
     };
   }
 
-  // Import and run score calculation
-  const { scoreCommand } = await import('./commands/score.js');
+  // Check for baseline
+  const baselinePath = join(cwd, '.ruvector', 'baseline.json');
+  let baseline = null;
+  let baselineWarning = null;
+
+  if (existsSync(baselinePath)) {
+    try {
+      baseline = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+      const baselineAge = (Date.now() - new Date(baseline.timestamp).getTime()) / (1000 * 60);
+      if (baselineAge > 60) {
+        baselineWarning = `Baseline is ${Math.round(baselineAge)} minutes old. Consider running kb_first_assess for fresh baseline.`;
+      }
+    } catch {}
+  }
+
+  // Phase-specific guidance
+  const phaseGuidance = {
+    0: ['Document project scope', 'Identify domain complexity', 'Assess KB-First suitability', 'Estimate resources', 'Make go/no-go decision'],
+    1: ['Map domain concepts', 'Design taxonomy', 'Define relationships', 'Plan query patterns', 'Review with stakeholders'],
+    1.5: ['Install enforcement hooks', 'Configure hook behavior', 'Train on project patterns', 'Verify hooks work'],
+    2: ['Create database tables', 'Add vector columns', 'Design indexes', 'Write migration scripts'],
+    3: ['Collect domain content', 'Process and clean data', 'Generate embeddings', 'Import to KB', 'Validate entries'],
+    4: ['Analyze KB coverage', 'Calculate quality score', 'Identify gaps', 'Prioritize fixes', 'Create remediation plan'],
+    5: ['Build search API', 'Implement code generation', 'Add citation system', 'Enable gap logging'],
+    6: ['Write unit tests', 'Create integration tests', 'Test KB accuracy', 'Performance tests', 'Edge case testing'],
+    7: ['Optimize queries', 'Tune indexes', 'Add caching', 'Run benchmarks'],
+    7.5: ['Verify test coverage ≥80%', 'Run E2E suite', 'Load testing', 'Build regression suite'],
+    8: ['Run code scan', 'Check imports', 'Verify source returns', 'Test startup', 'Check fallbacks', 'Validate attribution', 'Test confidence', 'Review gap logs'],
+    9: ['Audit dependencies', 'Check OWASP Top 10', 'Test SQL injection', 'Review auth', 'Audit secrets', 'Secure APIs'],
+    10: ['Write README', 'Document API', 'Schema documentation', 'Architecture docs', 'Operator guide'],
+    11: ['Setup infrastructure', 'Configure environments', 'Build CI/CD', 'Run migrations', 'Setup monitoring', 'Go live'],
+    11.5: ['Setup OpenTelemetry', 'Build KB dashboard', 'Configure alerts', 'Write runbooks'],
+    12: ['Define gap triage', 'Setup expert review', 'Document KB updates', 'Version control', 'A/B testing']
+  };
 
-  // Return score data
   return {
-    success: true,
-    message: 'Score calculated. Run `kb-first score --detailed` for full breakdown.',
-    hint: 'Use CLI for detailed output'
+    phase,
+    name: phaseInfo.name,
+    gate: phaseInfo.gate,
+    baseline: baseline ? {
+      score: baseline.total,
+      grade: baseline.grade,
+      timestamp: baseline.timestamp
+    } : null,
+    baselineWarning,
+    tasks: phaseGuidance[phase] || [],
+    reminder: '⚠️ IMPORTANT: Run kb_first_delta when phase work is complete to measure improvement',
+    gateRequirement: `Gate "${phaseInfo.gate}" must be satisfied to proceed`
   };
 }
 
-async function handleVerify(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+async function handleKbFirstDelta(cwd, args) {
+  const baselinePath = join(cwd, '.ruvector', 'baseline.json');
 
-  if (!existsSync(configPath)) {
+  if (!existsSync(baselinePath)) {
     return {
-      success: false,
-      error: 'Not a KB-First project. Run kb_first_init first.'
+      error: 'NO_BASELINE',
+      message: 'No baseline found. Run kb_first_assess first to establish baseline.',
+      action: 'Run kb_first_assess with saveBaseline=true'
     };
   }
 
-  const phase = args.phase;
-  const runAll = args.all;
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+  } catch {
+    return { error: 'CORRUPT_BASELINE', message: 'Baseline file is corrupt. Run kb_first_assess again.' };
+  }
 
-  return {
-    success: true,
-    message: phase
-      ? `Run: kb-first verify --phase=${phase}`
-      : runAll
-        ? 'Run: kb-first verify --all'
-        : 'Run: kb-first verify',
-    hint: 'Verification scripts require terminal execution'
+  const current = calculateScores(cwd);
+
+  const delta = {
+    total: current.total - baseline.total,
+    kb: current.kb.total - baseline.kb.total,
+    app: current.app.total - baseline.app.total,
+    process: current.process.total - baseline.process.total
   };
-}
 
-async function handleStatus(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+  const verdict = delta.total >= 0 ? 'PASS' : 'FAIL';
+  const canProceed = delta.total >= 0;
+
+  const result = {
+    verdict,
+    canProceed,
+    baseline: {
+      score: baseline.total,
+      grade: baseline.grade,
+      timestamp: baseline.timestamp
+    },
+    current: {
+      score: current.total,
+      grade: current.grade,
+      timestamp: current.timestamp
+    },
+    delta: {
+      total: delta.total > 0 ? `+${delta.total}` : `${delta.total}`,
+      kb: delta.kb > 0 ? `+${delta.kb}` : `${delta.kb}`,
+      app: delta.app > 0 ? `+${delta.app}` : `${delta.app}`,
+      process: delta.process > 0 ? `+${delta.process}` : `${delta.process}`
+    }
+  };
 
-  if (!existsSync(configPath)) {
-    return {
-      initialized: false,
-      error: 'Not a KB-First project'
-    };
+  if (!canProceed) {
+    result.blockReason = `Score dropped by ${Math.abs(delta.total)} points. You CANNOT proceed until score improves.`;
+    result.action = 'Fix issues causing score regression, then run kb_first_delta again.';
+  } else {
+    result.action = 'Run kb_first_gate to verify phase completion and proceed.';
   }
 
-  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  if (args.showBreakdown !== false) {
+    result.componentChanges = {
+      kb: {
+        before: baseline.kb.components,
+        after: current.kb.components
+      },
+      app: {
+        before: baseline.app.components,
+        after: current.app.components
+      },
+      process: {
+        before: baseline.process.components,
+        after: current.process.components
+      }
+    };
+  }
 
-  return {
-    initialized: true,
-    namespace: config.kbFirst?.namespace,
-    version: config.kbFirst?.version,
-    currentPhase: config.phases?.current || 0,
-    completedPhases: config.phases?.completed || [],
-    hooksEnabled: config.hooks?.enabled || false
-  };
+  return result;
 }
 
-async function handlePhase(cwd, args) {
-  const PHASES = {
-    0: { name: 'Assessment', subphases: 5 },
-    1: { name: 'KB Design', subphases: 5 },
-    1.5: { name: 'Hooks Setup', subphases: 4 },
-    2: { name: 'Schema Definition', subphases: 4 },
-    3: { name: 'KB Population', subphases: 5 },
-    4: { name: 'Scoring & Gaps', subphases: 5 },
-    5: { name: 'Integration', subphases: 4 },
-    6: { name: 'Testing', subphases: 5 },
-    7: { name: 'Optimization', subphases: 4 },
-    8: { name: 'Verification', subphases: 8 },
-    9: { name: 'Security', subphases: 6 },
-    10: { name: 'Documentation', subphases: 6 },
-    11: { name: 'Deployment', subphases: 6 }
-  };
-
+async function handleKbFirstGate(cwd, args) {
   const phase = args.phase;
   const phaseInfo = PHASES[phase];
 
   if (!phaseInfo) {
+    return { error: `Unknown phase: ${phase}` };
+  }
+
+  // Check baseline exists
+  const baselinePath = join(cwd, '.ruvector', 'baseline.json');
+  if (!existsSync(baselinePath)) {
     return {
-      error: `Unknown phase: ${phase}`,
-      validPhases: Object.keys(PHASES)
+      canProceed: false,
+      blockReason: 'GATE_BLOCKED: No baseline established. Run kb_first_assess first.',
+      phase,
+      phaseName: phaseInfo.name
+    };
+  }
+
+  // Check delta
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+  } catch {
+    return {
+      canProceed: false,
+      blockReason: 'GATE_BLOCKED: Corrupt baseline. Run kb_first_assess again.',
+      phase,
+      phaseName: phaseInfo.name
+    };
+  }
+
+  const current = calculateScores(cwd);
+  const delta = current.total - baseline.total;
+
+  if (delta < 0) {
+    return {
+      canProceed: false,
+      blockReason: `GATE_BLOCKED: Score regression detected (${delta} points). Fix issues before proceeding.`,
+      phase,
+      phaseName: phaseInfo.name,
+      baseline: baseline.total,
+      current: current.total,
+      delta
+    };
+  }
+
+  // Check gate-specific conditions
+  const configPath = join(cwd, '.ruvector', 'config.json');
+  let config = { phases: { current: 0, completed: [], gates: {} } };
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {}
+  }
+
+  // Phase-specific gate checks
+  let gateConditionMet = false;
+  let gateMessage = '';
+
+  switch (phaseInfo.gate) {
+    case 'kb_score_50':
+      gateConditionMet = current.kb.total >= 20; // 50% of 40
+      gateMessage = gateConditionMet ? 'KB score ≥50%' : `KB score ${current.kb.total}/40 < 50%`;
+      break;
+    case 'kb_score_80':
+      gateConditionMet = current.kb.total >= 32; // 80% of 40
+      gateMessage = gateConditionMet ? 'KB score ≥80%' : `KB score ${current.kb.total}/40 < 80%`;
+      break;
+    case 'coverage_80':
+      gateConditionMet = current.app.components.testCoverage >= 8; // 80% of 10
+      gateMessage = gateConditionMet ? 'Test coverage ≥80%' : `Test coverage ${current.app.components.testCoverage}/10 < 80%`;
+      break;
+    default:
+      // Default: pass if delta is non-negative
+      gateConditionMet = true;
+      gateMessage = 'Gate condition satisfied (positive delta)';
+  }
+
+  if (!gateConditionMet) {
+    return {
+      canProceed: false,
+      blockReason: `GATE_BLOCKED: ${gateMessage}`,
+      phase,
+      phaseName: phaseInfo.name,
+      gate: phaseInfo.gate
     };
   }
 
+  // Mark phase as completed
+  if (!config.phases.completed.includes(parseFloat(phase))) {
+    config.phases.completed.push(parseFloat(phase));
+  }
+  config.phases.gates[phaseInfo.gate] = true;
+
+  // Determine next phase
+  const phaseOrder = [0, 1, 1.5, 2, 3, 4, 5, 6, 7, 7.5, 8, 9, 10, 11, 11.5, 12];
+  const currentIdx = phaseOrder.indexOf(parseFloat(phase));
+  const nextPhase = currentIdx < phaseOrder.length - 1 ? phaseOrder[currentIdx + 1] : null;
+
+  if (nextPhase !== null) {
+    config.phases.current = nextPhase;
+  }
+
+  // Save config
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+  // Save current scores as new baseline for next phase
+  writeFileSync(baselinePath, JSON.stringify(current, null, 2));
+
   return {
+    canProceed: true,
     phase,
-    name: phaseInfo.name,
-    subphases: phaseInfo.subphases,
-    command: `kb-first phase ${phase}`
+    phaseName: phaseInfo.name,
+    gateStatus: 'PASSED',
+    gateMessage,
+    scoreImprovement: delta > 0 ? `+${delta}` : '0',
+    nextPhase,
+    nextPhaseName: nextPhase !== null ? PHASES[nextPhase]?.name : 'PROJECT COMPLETE',
+    action: nextPhase !== null
+      ? `Run kb_first_assess to establish baseline for Phase ${nextPhase}: ${PHASES[nextPhase]?.name}`
+      : 'All phases complete! Project ready for production.'
   };
 }
 
-async function handleHooks(cwd, args) {
-  const action = args.action;
+/**
+ * Handle MCP tool calls
+ */
+async function handleToolCall(toolName, args) {
+  const cwd = process.cwd();
 
-  return {
-    success: true,
-    action,
-    command: `kb-first hooks --${action}`,
-    hint: 'Hook management requires terminal execution'
-  };
+  switch (toolName) {
+    case 'kb_first_assess':
+      return await handleKbFirstAssess(cwd, args);
+    case 'kb_first_phase':
+      return await handleKbFirstPhase(cwd, args);
+    case 'kb_first_delta':
+      return await handleKbFirstDelta(cwd, args);
+    case 'kb_first_gate':
+      return await handleKbFirstGate(cwd, args);
+    default:
+      return { error: `Unknown tool: ${toolName}` };
+  }
 }
 
 /**
  * MCP Protocol Handler
  */
-function handleMCPMessage(message) {
+async function handleMCPMessage(message) {
   const { jsonrpc, id, method, params } = message;
 
   if (jsonrpc !== '2.0') {
-    return {
-      jsonrpc: '2.0',
-      id,
-      error: { code: -32600, message: 'Invalid JSON-RPC version' }
-    };
+    return { jsonrpc: '2.0', id, error: { code: -32600, message: 'Invalid JSON-RPC version' } };
   }
 
   switch (method) {
     case 'initialize':
       return {
-        jsonrpc: '2.0',
-        id,
+        jsonrpc: '2.0', id,
         result: {
           protocolVersion: MCP_VERSION,
-          serverInfo: {
-            name: SERVER_NAME,
-            version: SERVER_VERSION
-          },
-          capabilities: {
-            tools: {}
-          }
+          serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+          capabilities: { tools: {} }
         }
       };
 
     case 'tools/list':
-      return {
-        jsonrpc: '2.0',
-        id,
-        result: { tools: TOOLS }
-      };
+      return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
 
     case 'tools/call':
-      return handleToolCallAsync(id, params.name, params.arguments);
+      try {
+        const result = await handleToolCall(params.name, params.arguments || {});
+        return {
+          jsonrpc: '2.0', id,
+          result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+        };
+      } catch (error) {
+        return { jsonrpc: '2.0', id, error: { code: -32000, message: error.message } };
+      }
 
     default:
-      return {
-        jsonrpc: '2.0',
-        id,
-        error: { code: -32601, message: `Unknown method: ${method}` }
-      };
-  }
-}
-
-async function handleToolCallAsync(id, toolName, args) {
-  try {
-    const result = await handleToolCall(toolName, args || {});
-    return {
-      jsonrpc: '2.0',
-      id,
-      result: {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      }
-    };
-  } catch (error) {
-    return {
-      jsonrpc: '2.0',
-      id,
-      error: { code: -32000, message: error.message }
-    };
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Unknown method: ${method}` } };
   }
 }
 
@@ -366,47 +714,33 @@ async function handleToolCallAsync(id, toolName, args) {
  * Start MCP Server (stdio mode)
  */
 export async function startMCPServer(options = {}) {
-  console.error('RuvNet KB-First MCP Server starting...');
-  console.error(`Version: ${SERVER_VERSION}`);
-  console.error('Mode: stdio');
+  console.error(`RuvNet KB-First MCP Server v${SERVER_VERSION}`);
+  console.error('Architecture: Score-Driven | Tools: 4 | Phases: 15');
+  console.error('Philosophy: Scoring IS enforcement. No shortcuts.');
 
-  // Read from stdin
   let buffer = '';
-
   process.stdin.setEncoding('utf-8');
+
   process.stdin.on('data', async (chunk) => {
     buffer += chunk;
-
-    // Try to parse complete JSON-RPC messages
     const lines = buffer.split('\n');
     buffer = lines.pop() || '';
 
     for (const line of lines) {
       if (!line.trim()) continue;
-
       try {
-        const message = JSON.parse(line);
-        const response = await handleMCPMessage(message);
-
-        if (response) {
-          process.stdout.write(JSON.stringify(response) + '\n');
-        }
+        const response = await handleMCPMessage(JSON.parse(line));
+        if (response) process.stdout.write(JSON.stringify(response) + '\n');
       } catch (error) {
         console.error('Parse error:', error.message);
       }
     }
   });
 
-  process.stdin.on('end', () => {
-    console.error('MCP Server shutting down');
-    process.exit(0);
-  });
-
-  // Keep process alive
+  process.stdin.on('end', () => process.exit(0));
   process.stdin.resume();
 }
 
-// Run if called directly
 if (import.meta.url === `file://${process.argv[1]}`) {
   startMCPServer();
 }