ruvnet-kb-first 5.0.0 → 6.1.0

package/src/mcp-server.js

@@ -1,412 +1,1064 @@
 /**
- * RuvNet KB-First MCP Server
+ * RuvNet KB-First MCP Server - Granular Score-Driven Architecture
+ * Version 6.1.0
  *
- * Model Context Protocol server for Claude Code integration.
- * Provides KB-First tools directly within Claude Code.
+ * PHILOSOPHY: Granular scoring drives discipline.
+ * - Score each KB dimension 1-100 (completeness, depth, comprehensiveness, accuracy, freshness)
+ * - Score each phase readiness 1-100
+ * - Generate enhancement plan based on gaps
+ * - User confirms before execution
+ * - Post-verify: did we hit predicted scores?
+ *
+ * 5 Tools:
+ *   1. kb_first_assess   - Score ALL dimensions (KB quality + phase readiness)
+ *   2. kb_first_plan     - Generate enhancement plan with predicted improvements
+ *   3. kb_first_confirm  - User confirms readiness, locks in plan
+ *   4. kb_first_execute  - Execute plan phase by phase
+ *   5. kb_first_verify   - Post-verification: predicted vs actual, identify gaps
  *
  * 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.1.0';
+
+/**
+ * KB Quality Dimensions (each scored 1-100)
+ */
+const KB_DIMENSIONS = {
+  completeness: {
+    name: 'Completeness',
+    description: 'Does the KB cover all necessary domain topics?',
+    weight: 20
+  },
+  depth: {
+    name: 'Depth',
+    description: 'Is each topic covered with sufficient detail?',
+    weight: 20
+  },
+  comprehensiveness: {
+    name: 'Comprehensiveness',
+    description: 'Are edge cases, exceptions, and nuances included?',
+    weight: 20
+  },
+  accuracy: {
+    name: 'Accuracy',
+    description: 'Is the information correct and up-to-date?',
+    weight: 20
+  },
+  freshness: {
+    name: 'Freshness',
+    description: 'How recently was the KB updated?',
+    weight: 10
+  },
+  attribution: {
+    name: 'Attribution',
+    description: 'Are sources and experts properly cited?',
+    weight: 10
+  }
+};
+
+/**
+ * Phase Definitions with readiness criteria
+ */
+const PHASES = {
+  0: {
+    name: 'Assessment',
+    criteria: ['Project scope documented', 'Domain complexity identified', 'KB-First suitability confirmed', 'Resources estimated']
+  },
+  1: {
+    name: 'KB Design',
+    criteria: ['Domain concepts mapped', 'Taxonomy designed', 'Relationships defined', 'Query patterns planned']
+  },
+  1.5: {
+    name: 'Hooks Setup',
+    criteria: ['Hooks installed', 'Configuration complete', 'Patterns trained', 'Verification passing']
+  },
+  2: {
+    name: 'Schema Definition',
+    criteria: ['Tables created', 'Vector columns added', 'Indexes designed', 'Migrations written']
+  },
+  3: {
+    name: 'KB Population',
+    criteria: ['Content collected', 'Data cleaned', 'Embeddings generated', 'Import validated']
+  },
+  4: {
+    name: 'Scoring & Gaps',
+    criteria: ['Coverage analyzed', 'Quality scored', 'Gaps identified', 'Remediation planned']
+  },
+  5: {
+    name: 'Integration',
+    criteria: ['Search API built', 'Code generation working', 'Citation system active', 'Gap logging enabled']
+  },
+  6: {
+    name: 'Testing',
+    criteria: ['Unit tests written', 'Integration tests passing', 'Accuracy validated', 'Edge cases covered']
+  },
+  7: {
+    name: 'Optimization',
+    criteria: ['Queries optimized', 'Indexes tuned', 'Caching implemented', 'Benchmarks passing']
+  },
+  8: {
+    name: 'Verification',
+    criteria: ['Code scan clean', 'Imports verified', 'Sources return', 'Startup working', 'Fallbacks tested', 'Attribution valid', 'Confidence scores present', 'Gap logging active']
+  },
+  9: {
+    name: 'Security',
+    criteria: ['Dependencies audited', 'OWASP checked', 'SQL injection tested', 'Auth reviewed', 'Secrets secured', 'APIs protected']
+  },
+  10: {
+    name: 'Documentation',
+    criteria: ['README complete', 'API documented', 'Schema documented', 'Architecture documented', 'Operator guide written']
+  },
+  11: {
+    name: 'Deployment',
+    criteria: ['Infrastructure ready', 'Environments configured', 'CI/CD built', 'Migrations run', 'Monitoring active', 'Go-live complete']
+  }
+};
 
 /**
- * Available MCP Tools
+ * MCP Tools
  */
 const TOOLS = [
   {
-    name: 'kb_first_init',
-    description: 'Initialize KB-First structure in the current project',
+    name: 'kb_first_assess',
+    description: `Score ALL dimensions of KB quality and phase readiness (each 1-100).
+
+KB Quality Dimensions:
+- Completeness: Does KB cover all domain topics?
+- Depth: Is each topic detailed enough?
+- Comprehensiveness: Are edge cases included?
+- Accuracy: Is information correct?
+- Freshness: How recently updated?
+- Attribution: Are sources cited?
+
+Phase Readiness:
+- Each of 12 phases scored 1-100 based on criteria completion
+
+Returns granular scores that reveal exactly where gaps exist.
+This is your BASELINE for planning.`,
     inputSchema: {
       type: 'object',
       properties: {
-        force: {
-          type: 'boolean',
-          description: 'Overwrite existing configuration'
-        },
-        template: {
-          type: 'string',
-          enum: ['basic', 'api', 'fullstack'],
-          description: 'Project template type'
-        }
+        projectPath: { type: 'string', description: 'Path to project (default: current directory)' }
       }
     }
   },
   {
-    name: 'kb_first_score',
-    description: 'Calculate KB-First compliance score for the project',
+    name: 'kb_first_plan',
+    description: `Generate enhancement plan based on assessment scores.
+
+Analyzes gaps (scores below threshold) and creates:
+- Prioritized list of enhancements
+- Predicted score improvements for each
+- Estimated effort
+- Execution order
+
+The plan gives you a concrete game plan so you don't lose the thread.
+Returns the plan for user review before execution.`,
     inputSchema: {
       type: 'object',
       properties: {
-        detailed: {
-          type: 'boolean',
-          description: 'Show detailed breakdown'
-        }
+        threshold: { type: 'number', description: 'Minimum acceptable score (default: 80)', default: 80 },
+        focusArea: { type: 'string', enum: ['kb', 'phases', 'all'], description: 'What to focus on', default: 'all' }
       }
     }
   },
   {
-    name: 'kb_first_verify',
-    description: 'Run KB-First verification checks',
+    name: 'kb_first_confirm',
+    description: `User confirms readiness to execute enhancement plan.
+
+Shows the plan summary and asks for confirmation.
+Once confirmed, the plan is locked and execution can begin.
+
+This ensures user consent before making changes.`,
     inputSchema: {
       type: 'object',
       properties: {
-        phase: {
-          type: 'number',
-          description: 'Verify specific phase (0-11)'
-        },
-        all: {
-          type: 'boolean',
-          description: 'Run all verification scripts'
-        }
-      }
+        confirmed: { type: 'boolean', description: 'User confirms readiness to proceed' }
+      },
+      required: ['confirmed']
     }
   },
   {
-    name: 'kb_first_status',
-    description: 'Show KB-First project status',
+    name: 'kb_first_execute',
+    description: `Execute the confirmed enhancement plan.
+
+Works through the plan systematically:
+- Shows current task
+- Provides guidance for completion
+- Tracks progress
+- Updates predicted scores
+
+Call repeatedly to work through each enhancement.`,
     inputSchema: {
       type: 'object',
       properties: {
-        detailed: {
-          type: 'boolean',
-          description: 'Show detailed status'
-        }
+        taskComplete: { type: 'boolean', description: 'Mark current task as complete' }
       }
     }
   },
   {
-    name: 'kb_first_phase',
-    description: 'Get information about a specific build phase',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        phase: {
-          type: 'number',
-          description: 'Phase number (0, 1, 1.5, 2-11)'
-        }
-      },
-      required: ['phase']
-    }
-  },
-  {
-    name: 'kb_first_hooks',
-    description: 'Manage KB-First hooks',
+    name: 'kb_first_verify',
+    description: `Post-verification: Compare predicted vs actual scores.
+
+Re-scores everything and compares to predictions:
+- Which improvements were achieved?
+- Which fell short?
+- What gaps remain?
+- What's the next priority?
+
+This closes the loop and ensures you delivered what you promised.`,
     inputSchema: {
       type: 'object',
       properties: {
-        action: {
-          type: 'string',
-          enum: ['install', 'verify', 'train', 'status'],
-          description: 'Hook action to perform'
-        }
-      },
-      required: ['action']
+        detailed: { type: 'boolean', description: 'Show detailed comparison', default: true }
+      }
     }
   }
 ];
 
 /**
- * Handle MCP tool calls
+ * Score KB Quality Dimensions (1-100 each)
  */
-async function handleToolCall(toolName, args) {
-  const cwd = process.cwd();
+function scoreKBDimensions(cwd) {
+  const scores = {};
+  const kbDir = join(cwd, 'src', 'kb');
+  const docsDir = join(cwd, 'docs');
+  const ruvectorDir = join(cwd, '.ruvector');
 
-  switch (toolName) {
-    case 'kb_first_init':
-      return await handleInit(cwd, args);
+  // Count KB entries and docs
+  let kbEntries = 0;
+  let docFiles = 0;
+  let totalContent = 0;
 
-    case 'kb_first_score':
-      return await handleScore(cwd, args);
+  if (existsSync(kbDir)) {
+    try {
+      const files = readdirSync(kbDir);
+      kbEntries = files.length;
+      for (const f of files) {
+        try {
+          const content = readFileSync(join(kbDir, f), 'utf-8');
+          totalContent += content.length;
+        } catch {}
+      }
+    } catch {}
+  }
 
-    case 'kb_first_verify':
-      return await handleVerify(cwd, args);
+  if (existsSync(docsDir)) {
+    try {
+      docFiles = readdirSync(docsDir).filter(f => f.endsWith('.md')).length;
+    } catch {}
+  }
 
-    case 'kb_first_status':
-      return await handleStatus(cwd, args);
+  // Completeness: Based on number of KB entries and docs
+  // 0 entries = 0, 5 entries = 50, 10+ entries = 100
+  scores.completeness = {
+    score: Math.min(100, Math.max(0, kbEntries * 10 + docFiles * 10)),
+    reason: `${kbEntries} KB entries, ${docFiles} doc files`,
+    improvement: kbEntries < 10 ? `Add ${10 - kbEntries} more KB entries` : 'Adequate coverage'
+  };
 
-    case 'kb_first_phase':
-      return await handlePhase(cwd, args);
+  // Depth: Based on average content length
+  // < 500 chars avg = shallow, > 2000 = deep
+  const avgLength = kbEntries > 0 ? totalContent / kbEntries : 0;
+  scores.depth = {
+    score: Math.min(100, Math.max(0, Math.round(avgLength / 20))),
+    reason: `Average entry length: ${Math.round(avgLength)} chars`,
+    improvement: avgLength < 2000 ? 'Add more detail to KB entries' : 'Good depth'
+  };
 
-    case 'kb_first_hooks':
-      return await handleHooks(cwd, args);
+  // Comprehensiveness: Check for edge case documentation
+  let edgeCaseScore = 0;
+  const srcDir = join(cwd, 'src');
+  if (existsSync(srcDir)) {
+    try {
+      const files = globSync('**/*.{ts,tsx,js,jsx,py}', { cwd: srcDir });
+      for (const f of files) {
+        try {
+          const content = readFileSync(join(srcDir, f), 'utf-8');
+          if (content.includes('edge case') || content.includes('exception') || content.includes('fallback')) {
+            edgeCaseScore += 10;
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  scores.comprehensiveness = {
+    score: Math.min(100, edgeCaseScore + (kbEntries * 5)),
+    reason: `Edge case handling detected in ${Math.floor(edgeCaseScore / 10)} files`,
+    improvement: edgeCaseScore < 50 ? 'Document edge cases and exceptions' : 'Good coverage'
+  };
 
-    default:
-      return {
-        error: `Unknown tool: ${toolName}`
-      };
+  // Accuracy: Based on presence of verification/testing
+  let accuracyScore = 50; // Base score
+  if (existsSync(join(cwd, 'tests')) || existsSync(join(cwd, '__tests__'))) accuracyScore += 25;
+  if (existsSync(join(cwd, '.ruvector', 'config.json'))) accuracyScore += 15;
+  if (existsSync(join(cwd, 'CHANGELOG.md'))) accuracyScore += 10;
+  scores.accuracy = {
+    score: Math.min(100, accuracyScore),
+    reason: accuracyScore > 75 ? 'Tests and verification present' : 'Limited verification',
+    improvement: accuracyScore < 80 ? 'Add tests and validation' : 'Good accuracy controls'
+  };
+
+  // Freshness: Based on last modification
+  let freshnessScore = 0;
+  if (existsSync(ruvectorDir)) {
+    try {
+      const stat = statSync(ruvectorDir);
+      const daysSince = (Date.now() - stat.mtime.getTime()) / (1000 * 60 * 60 * 24);
+      if (daysSince < 1) freshnessScore = 100;
+      else if (daysSince < 7) freshnessScore = 80;
+      else if (daysSince < 30) freshnessScore = 50;
+      else if (daysSince < 90) freshnessScore = 25;
+      else freshnessScore = 10;
+    } catch {}
   }
-}
+  scores.freshness = {
+    score: freshnessScore,
+    reason: freshnessScore > 50 ? 'Recently updated' : 'Stale - needs refresh',
+    improvement: freshnessScore < 80 ? 'Update KB content' : 'Fresh'
+  };
+
+  // Attribution: Check for citations in code
+  let attributionScore = 0;
+  if (existsSync(srcDir)) {
+    try {
+      const files = globSync('**/*.{ts,tsx,js,jsx,py}', { cwd: srcDir });
+      let filesWithCitation = 0;
+      for (const f of files) {
+        try {
+          const content = readFileSync(join(srcDir, f), 'utf-8');
+          if (content.includes('KB-Generated:') || content.includes('Sources:') || content.includes('@kb-source')) {
+            filesWithCitation++;
+          }
+        } catch {}
+      }
+      attributionScore = files.length > 0 ? Math.round((filesWithCitation / files.length) * 100) : 100;
+    } catch {}
+  } else {
+    attributionScore = 100; // No code = not applicable
+  }
+  scores.attribution = {
+    score: attributionScore,
+    reason: `${attributionScore}% of code files have KB citations`,
+    improvement: attributionScore < 80 ? 'Add KB citations to code files' : 'Good attribution'
+  };
 
-async function handleInit(cwd, args) {
-  const { initCommand } = await import('./commands/init.js');
+  return scores;
+}
 
-  // Run init (capture output)
+/**
+ * Score Phase Readiness (1-100 each)
+ */
+function scorePhaseReadiness(cwd) {
+  const scores = {};
   const configPath = join(cwd, '.ruvector', 'config.json');
-  const wasInitialized = existsSync(configPath);
+  let config = { phases: { completed: [], gates: {} } };
 
-  try {
-    await initCommand({
-      force: args.force || false,
-      template: args.template || 'basic',
-      hooks: true
-    });
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {}
+  }
 
-    return {
-      success: true,
-      message: wasInitialized && !args.force
-        ? 'Project already initialized'
-        : 'KB-First project initialized successfully',
-      configPath
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error.message
+  const completed = config.phases?.completed || [];
+  const gates = config.phases?.gates || {};
+
+  for (const [phaseNum, phaseInfo] of Object.entries(PHASES)) {
+    const num = parseFloat(phaseNum);
+    const isCompleted = completed.includes(num);
+    const criteriaCount = phaseInfo.criteria.length;
+
+    // Check which criteria are met
+    let metCriteria = 0;
+    const unmetCriteria = [];
+
+    for (const criterion of phaseInfo.criteria) {
+      // Simplified check - in real implementation, this would be more sophisticated
+      if (isCompleted || checkCriterion(cwd, num, criterion)) {
+        metCriteria++;
+      } else {
+        unmetCriteria.push(criterion);
+      }
+    }
+
+    const score = Math.round((metCriteria / criteriaCount) * 100);
+
+    scores[phaseNum] = {
+      name: phaseInfo.name,
+      score,
+      metCriteria,
+      totalCriteria: criteriaCount,
+      unmet: unmetCriteria,
+      completed: isCompleted
     };
   }
+
+  return scores;
 }
 
-async function handleScore(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+/**
+ * Check if a criterion is met (simplified)
+ */
+function checkCriterion(cwd, phase, criterion) {
+  // Check for common indicators
+  const criterionLower = criterion.toLowerCase();
 
-  if (!existsSync(configPath)) {
-    return {
-      success: false,
-      error: 'Not a KB-First project. Run kb_first_init first.'
+  if (criterionLower.includes('documented')) {
+    return existsSync(join(cwd, 'docs')) || existsSync(join(cwd, 'README.md'));
+  }
+  if (criterionLower.includes('tests')) {
+    return existsSync(join(cwd, 'tests')) || existsSync(join(cwd, '__tests__'));
+  }
+  if (criterionLower.includes('config')) {
+    return existsSync(join(cwd, '.ruvector', 'config.json'));
+  }
+  if (criterionLower.includes('hooks')) {
+    return existsSync(join(cwd, '.ruvector', 'hooks'));
+  }
+  if (criterionLower.includes('schema') || criterionLower.includes('tables')) {
+    return existsSync(join(cwd, 'templates', 'schema.sql'));
+  }
+
+  return false;
+}
+
+/**
+ * Calculate overall weighted scores
+ */
+function calculateOverallScores(kbScores, phaseScores) {
+  // KB Overall (weighted average)
+  let kbTotal = 0;
+  let kbWeightTotal = 0;
+  for (const [dim, info] of Object.entries(KB_DIMENSIONS)) {
+    if (kbScores[dim]) {
+      kbTotal += kbScores[dim].score * info.weight;
+      kbWeightTotal += info.weight;
+    }
+  }
+  const kbOverall = kbWeightTotal > 0 ? Math.round(kbTotal / kbWeightTotal) : 0;
+
+  // Phase Overall (average)
+  const phaseValues = Object.values(phaseScores);
+  const phaseOverall = phaseValues.length > 0
+    ? Math.round(phaseValues.reduce((sum, p) => sum + p.score, 0) / phaseValues.length)
+    : 0;
+
+  // Combined Overall
+  const overall = Math.round((kbOverall * 0.5) + (phaseOverall * 0.5));
+
+  return { kbOverall, phaseOverall, overall };
+}
+
+/**
+ * Tool Handlers
+ */
+async function handleAssess(cwd, args) {
+  const kbScores = scoreKBDimensions(cwd);
+  const phaseScores = scorePhaseReadiness(cwd);
+  const overall = calculateOverallScores(kbScores, phaseScores);
+
+  // Save assessment
+  const ruvectorDir = join(cwd, '.ruvector');
+  if (!existsSync(ruvectorDir)) {
+    mkdirSync(ruvectorDir, { recursive: true });
+  }
+
+  const assessment = {
+    timestamp: new Date().toISOString(),
+    kb: kbScores,
+    phases: phaseScores,
+    overall
+  };
+
+  writeFileSync(join(ruvectorDir, 'assessment.json'), JSON.stringify(assessment, null, 2));
+
+  // Format for display
+  const kbSummary = {};
+  for (const [dim, data] of Object.entries(kbScores)) {
+    kbSummary[dim] = {
+      score: data.score,
+      reason: data.reason
     };
   }
 
-  // Import and run score calculation
-  const { scoreCommand } = await import('./commands/score.js');
+  const phaseSummary = {};
+  for (const [num, data] of Object.entries(phaseScores)) {
+    phaseSummary[`Phase ${num}: ${data.name}`] = {
+      score: data.score,
+      criteria: `${data.metCriteria}/${data.totalCriteria}`,
+      status: data.completed ? 'COMPLETE' : (data.score >= 80 ? 'READY' : 'GAPS')
+    };
+  }
 
-  // Return score data
   return {
-    success: true,
-    message: 'Score calculated. Run `kb-first score --detailed` for full breakdown.',
-    hint: 'Use CLI for detailed output'
+    action: 'ASSESSMENT_COMPLETE',
+    timestamp: assessment.timestamp,
+    overallScores: {
+      kb: `${overall.kbOverall}/100`,
+      phases: `${overall.phaseOverall}/100`,
+      combined: `${overall.overall}/100`
+    },
+    kbQuality: kbSummary,
+    phaseReadiness: phaseSummary,
+    nextStep: 'Run kb_first_plan to generate enhancement plan based on gaps'
   };
 }
 
-async function handleVerify(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+async function handlePlan(cwd, args) {
+  const assessmentPath = join(cwd, '.ruvector', 'assessment.json');
 
-  if (!existsSync(configPath)) {
+  if (!existsSync(assessmentPath)) {
     return {
-      success: false,
-      error: 'Not a KB-First project. Run kb_first_init first.'
+      error: 'NO_ASSESSMENT',
+      message: 'No assessment found. Run kb_first_assess first.',
+      action: 'Run kb_first_assess to score KB and phase readiness'
     };
   }
 
-  const phase = args.phase;
-  const runAll = args.all;
+  const assessment = JSON.parse(readFileSync(assessmentPath, 'utf-8'));
+  const threshold = args.threshold || 80;
+  const focusArea = args.focusArea || 'all';
+
+  const enhancements = [];
+  let taskId = 1;
+
+  // Find KB gaps
+  if (focusArea === 'all' || focusArea === 'kb') {
+    for (const [dim, data] of Object.entries(assessment.kb)) {
+      if (data.score < threshold) {
+        const gap = threshold - data.score;
+        enhancements.push({
+          id: taskId++,
+          area: 'KB Quality',
+          dimension: KB_DIMENSIONS[dim]?.name || dim,
+          currentScore: data.score,
+          targetScore: threshold,
+          predictedImprovement: gap,
+          task: data.improvement,
+          priority: gap > 30 ? 'HIGH' : (gap > 15 ? 'MEDIUM' : 'LOW'),
+          effort: gap > 30 ? 'Large' : (gap > 15 ? 'Medium' : 'Small')
+        });
+      }
+    }
+  }
+
+  // Find Phase gaps
+  if (focusArea === 'all' || focusArea === 'phases') {
+    for (const [num, data] of Object.entries(assessment.phases)) {
+      if (data.score < threshold && !data.completed) {
+        const gap = threshold - data.score;
+        enhancements.push({
+          id: taskId++,
+          area: 'Phase Readiness',
+          dimension: `Phase ${num}: ${data.name}`,
+          currentScore: data.score,
+          targetScore: threshold,
+          predictedImprovement: gap,
+          task: `Complete: ${data.unmet.slice(0, 3).join(', ')}${data.unmet.length > 3 ? '...' : ''}`,
+          priority: gap > 30 ? 'HIGH' : (gap > 15 ? 'MEDIUM' : 'LOW'),
+          effort: gap > 30 ? 'Large' : (gap > 15 ? 'Medium' : 'Small')
+        });
+      }
+    }
+  }
+
+  // Sort by priority
+  const priorityOrder = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  enhancements.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  // Calculate predicted totals
+  const predictedKBImprovement = enhancements
+    .filter(e => e.area === 'KB Quality')
+    .reduce((sum, e) => sum + e.predictedImprovement, 0);
+
+  const predictedPhaseImprovement = enhancements
+    .filter(e => e.area === 'Phase Readiness')
+    .reduce((sum, e) => sum + e.predictedImprovement, 0);
+
+  const plan = {
+    timestamp: new Date().toISOString(),
+    threshold,
+    baselineScores: assessment.overall,
+    enhancements,
+    predictions: {
+      kbImprovement: `+${Math.round(predictedKBImprovement / 6)}`, // Average across 6 dimensions
+      phaseImprovement: `+${Math.round(predictedPhaseImprovement / Object.keys(PHASES).length)}`,
+      tasksCount: enhancements.length,
+      highPriority: enhancements.filter(e => e.priority === 'HIGH').length,
+      mediumPriority: enhancements.filter(e => e.priority === 'MEDIUM').length,
+      lowPriority: enhancements.filter(e => e.priority === 'LOW').length
+    },
+    confirmed: false,
+    currentTaskIndex: 0
+  };
+
+  writeFileSync(join(cwd, '.ruvector', 'plan.json'), JSON.stringify(plan, null, 2));
 
   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'
+    action: 'PLAN_GENERATED',
+    summary: {
+      totalTasks: enhancements.length,
+      highPriority: plan.predictions.highPriority,
+      mediumPriority: plan.predictions.mediumPriority,
+      lowPriority: plan.predictions.lowPriority
+    },
+    predictedImprovements: {
+      kb: plan.predictions.kbImprovement,
+      phases: plan.predictions.phaseImprovement
+    },
+    enhancements: enhancements.map(e => ({
+      id: e.id,
+      priority: e.priority,
+      area: e.dimension,
+      current: e.currentScore,
+      target: e.targetScore,
+      task: e.task
+    })),
+    nextStep: 'Review the plan above. Run kb_first_confirm with confirmed=true when ready to proceed.'
   };
 }
 
-async function handleStatus(cwd, args) {
-  const configPath = join(cwd, '.ruvector', 'config.json');
+async function handleConfirm(cwd, args) {
+  const planPath = join(cwd, '.ruvector', 'plan.json');
+
+  if (!existsSync(planPath)) {
+    return {
+      error: 'NO_PLAN',
+      message: 'No plan found. Run kb_first_plan first.',
+      action: 'Run kb_first_plan to generate enhancement plan'
+    };
+  }
 
-  if (!existsSync(configPath)) {
+  if (!args.confirmed) {
     return {
-      initialized: false,
-      error: 'Not a KB-First project'
+      action: 'CONFIRMATION_REQUIRED',
+      message: 'You must confirm with confirmed=true to proceed.',
+      hint: 'Review the plan from kb_first_plan, then confirm when ready.'
     };
   }
 
-  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  const plan = JSON.parse(readFileSync(planPath, 'utf-8'));
+  plan.confirmed = true;
+  plan.confirmedAt = new Date().toISOString();
+  plan.currentTaskIndex = 0;
+
+  writeFileSync(planPath, JSON.stringify(plan, null, 2));
+
+  const firstTask = plan.enhancements[0];
 
   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
+    action: 'PLAN_CONFIRMED',
+    confirmedAt: plan.confirmedAt,
+    totalTasks: plan.enhancements.length,
+    message: 'Plan locked. Ready to execute.',
+    firstTask: firstTask ? {
+      id: firstTask.id,
+      priority: firstTask.priority,
+      area: firstTask.dimension,
+      task: firstTask.task,
+      currentScore: firstTask.currentScore,
+      targetScore: firstTask.targetScore
+    } : null,
+    nextStep: 'Run kb_first_execute to work through the plan'
   };
 }
 
-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 handleExecute(cwd, args) {
+  const planPath = join(cwd, '.ruvector', 'plan.json');
+
+  if (!existsSync(planPath)) {
+    return {
+      error: 'NO_PLAN',
+      message: 'No plan found. Run kb_first_plan first.'
+    };
+  }
+
+  const plan = JSON.parse(readFileSync(planPath, 'utf-8'));
+
+  if (!plan.confirmed) {
+    return {
+      error: 'PLAN_NOT_CONFIRMED',
+      message: 'Plan not confirmed. Run kb_first_confirm first.',
+      action: 'Run kb_first_confirm with confirmed=true'
+    };
+  }
 
-  const phase = args.phase;
-  const phaseInfo = PHASES[phase];
+  // Mark current task complete if requested
+  if (args.taskComplete && plan.currentTaskIndex < plan.enhancements.length) {
+    plan.enhancements[plan.currentTaskIndex].completed = true;
+    plan.enhancements[plan.currentTaskIndex].completedAt = new Date().toISOString();
+    plan.currentTaskIndex++;
+    writeFileSync(planPath, JSON.stringify(plan, null, 2));
+  }
 
-  if (!phaseInfo) {
+  // Check if all done
+  if (plan.currentTaskIndex >= plan.enhancements.length) {
     return {
-      error: `Unknown phase: ${phase}`,
-      validPhases: Object.keys(PHASES)
+      action: 'EXECUTION_COMPLETE',
+      message: 'All tasks completed!',
+      completedTasks: plan.enhancements.length,
+      nextStep: 'Run kb_first_verify to compare predicted vs actual improvements'
     };
   }
 
+  const currentTask = plan.enhancements[plan.currentTaskIndex];
+  const completedCount = plan.enhancements.filter(e => e.completed).length;
+
   return {
-    phase,
-    name: phaseInfo.name,
-    subphases: phaseInfo.subphases,
-    command: `kb-first phase ${phase}`
+    action: 'EXECUTING',
+    progress: {
+      completed: completedCount,
+      total: plan.enhancements.length,
+      percent: Math.round((completedCount / plan.enhancements.length) * 100)
+    },
+    currentTask: {
+      id: currentTask.id,
+      priority: currentTask.priority,
+      area: currentTask.dimension,
+      task: currentTask.task,
+      currentScore: currentTask.currentScore,
+      targetScore: currentTask.targetScore,
+      predictedImprovement: `+${currentTask.predictedImprovement}`
+    },
+    guidance: getTaskGuidance(currentTask),
+    nextStep: 'Complete the task above, then run kb_first_execute with taskComplete=true'
   };
 }
 
-async function handleHooks(cwd, args) {
-  const action = args.action;
+function getTaskGuidance(task) {
+  // Provide specific guidance based on task type
+  if (task.area === 'KB Quality') {
+    switch (task.dimension) {
+      case 'Completeness':
+        return 'Add more KB entries covering missing domain topics. Each entry should be in src/kb/ directory.';
+      case 'Depth':
+        return 'Expand existing KB entries with more detail. Target 2000+ characters per entry.';
+      case 'Comprehensiveness':
+        return 'Document edge cases, exceptions, and nuances in your KB entries.';
+      case 'Accuracy':
+        return 'Add tests to validate KB content. Create a tests/ directory with validation tests.';
+      case 'Freshness':
+        return 'Update KB content with latest information. Touch .ruvector/ to update timestamps.';
+      case 'Attribution':
+        return 'Add KB-Generated: headers to code files citing their KB sources.';
+      default:
+        return task.task;
+    }
+  }
+  return task.task;
+}
 
-  return {
-    success: true,
-    action,
-    command: `kb-first hooks --${action}`,
-    hint: 'Hook management requires terminal execution'
+async function handleVerify(cwd, args) {
+  const planPath = join(cwd, '.ruvector', 'plan.json');
+  const assessmentPath = join(cwd, '.ruvector', 'assessment.json');
+  const TARGET_SCORE = 98; // Recursive loop until we hit 98+
+
+  if (!existsSync(planPath) || !existsSync(assessmentPath)) {
+    return {
+      error: 'MISSING_DATA',
+      message: 'Missing plan or assessment. Run kb_first_assess and kb_first_plan first.'
+    };
+  }
+
+  const plan = JSON.parse(readFileSync(planPath, 'utf-8'));
+  const originalAssessment = JSON.parse(readFileSync(assessmentPath, 'utf-8'));
+
+  // Re-assess current state
+  const currentKB = scoreKBDimensions(cwd);
+  const currentPhases = scorePhaseReadiness(cwd);
+  const currentOverall = calculateOverallScores(currentKB, currentPhases);
+
+  // Compare predictions vs actual
+  const comparison = {
+    kb: {},
+    phases: {}
   };
+
+  // Compare KB dimensions
+  for (const [dim, original] of Object.entries(originalAssessment.kb)) {
+    const current = currentKB[dim];
+    const enhancement = plan.enhancements.find(e => e.dimension === KB_DIMENSIONS[dim]?.name);
+
+    comparison.kb[dim] = {
+      before: original.score,
+      after: current.score,
+      actual: current.score - original.score,
+      predicted: enhancement?.predictedImprovement || 0,
+      hit: current.score >= TARGET_SCORE
+    };
+  }
+
+  // Compare phases
+  for (const [num, original] of Object.entries(originalAssessment.phases)) {
+    const current = currentPhases[num];
+    const enhancement = plan.enhancements.find(e => e.dimension === `Phase ${num}: ${original.name}`);
+
+    comparison.phases[num] = {
+      name: original.name,
+      before: original.score,
+      after: current.score,
+      actual: current.score - original.score,
+      predicted: enhancement?.predictedImprovement || 0,
+      hit: current.score >= TARGET_SCORE
+    };
+  }
+
+  // Calculate summary
+  const kbHits = Object.values(comparison.kb).filter(c => c.hit).length;
+  const kbTotal = Object.keys(comparison.kb).length;
+  const phaseHits = Object.values(comparison.phases).filter(c => c.hit).length;
+  const phaseTotal = Object.keys(comparison.phases).length;
+
+  // Identify remaining gaps (anything below 98)
+  const remainingGaps = [];
+  for (const [dim, data] of Object.entries(comparison.kb)) {
+    if (data.after < TARGET_SCORE) {
+      remainingGaps.push({
+        area: 'KB Quality',
+        dimension: KB_DIMENSIONS[dim]?.name || dim,
+        currentScore: data.after,
+        targetScore: TARGET_SCORE,
+        gap: TARGET_SCORE - data.after
+      });
+    }
+  }
+  for (const [num, data] of Object.entries(comparison.phases)) {
+    if (data.after < TARGET_SCORE) {
+      remainingGaps.push({
+        area: 'Phase Readiness',
+        dimension: `Phase ${num}: ${data.name}`,
+        currentScore: data.after,
+        targetScore: TARGET_SCORE,
+        gap: TARGET_SCORE - data.after
+      });
+    }
+  }
+
+  // Track iteration count
+  let iterationCount = plan.iterationCount || 1;
+
+  // Save verification
+  const verification = {
+    timestamp: new Date().toISOString(),
+    iteration: iterationCount,
+    original: originalAssessment.overall,
+    current: currentOverall,
+    comparison,
+    remainingGaps,
+    targetScore: TARGET_SCORE,
+    targetMet: currentOverall.overall >= TARGET_SCORE
+  };
+  writeFileSync(join(cwd, '.ruvector', 'verification.json'), JSON.stringify(verification, null, 2));
+
+  const result = {
+    action: 'VERIFICATION_COMPLETE',
+    iteration: iterationCount,
+    targetScore: TARGET_SCORE,
+    summary: {
+      kbAt98Plus: `${kbHits}/${kbTotal}`,
+      phasesAt98Plus: `${phaseHits}/${phaseTotal}`,
+      overallImprovement: {
+        kb: `${originalAssessment.overall.kbOverall} → ${currentOverall.kbOverall} (${currentOverall.kbOverall - originalAssessment.overall.kbOverall >= 0 ? '+' : ''}${currentOverall.kbOverall - originalAssessment.overall.kbOverall})`,
+        phases: `${originalAssessment.overall.phaseOverall} → ${currentOverall.phaseOverall} (${currentOverall.phaseOverall - originalAssessment.overall.phaseOverall >= 0 ? '+' : ''}${currentOverall.phaseOverall - originalAssessment.overall.phaseOverall})`,
+        combined: `${originalAssessment.overall.overall} → ${currentOverall.overall} (${currentOverall.overall - originalAssessment.overall.overall >= 0 ? '+' : ''}${currentOverall.overall - originalAssessment.overall.overall})`
+      }
+    }
+  };
+
+  if (args.detailed) {
+    result.kbComparison = comparison.kb;
+    result.phaseComparison = comparison.phases;
+  }
+
+  // Check if we've hit the target
+  if (currentOverall.overall >= TARGET_SCORE && remainingGaps.length === 0) {
+    result.status = 'TARGET_ACHIEVED';
+    result.message = `🎯 All scores at ${TARGET_SCORE}+ after ${iterationCount} iteration(s)!`;
+    result.remainingGaps = 'None - all targets met!';
+    result.nextStep = 'Excellence achieved. Ready for production.';
+  } else {
+    // RECURSIVE: Auto-generate next plan
+    result.status = 'NEEDS_MORE_WORK';
+    result.message = `Score ${currentOverall.overall}/100 - target is ${TARGET_SCORE}. Generating next iteration plan...`;
+    result.remainingGaps = remainingGaps;
+
+    // Update assessment with current scores for next iteration
+    const newAssessment = {
+      timestamp: new Date().toISOString(),
+      kb: currentKB,
+      phases: currentPhases,
+      overall: currentOverall,
+      previousIteration: iterationCount
+    };
+    writeFileSync(join(cwd, '.ruvector', 'assessment.json'), JSON.stringify(newAssessment, null, 2));
+
+    // Auto-generate new plan for remaining gaps
+    const newEnhancements = remainingGaps.map((gap, idx) => ({
+      id: idx + 1,
+      area: gap.area,
+      dimension: gap.dimension,
+      currentScore: gap.currentScore,
+      targetScore: TARGET_SCORE,
+      predictedImprovement: gap.gap,
+      task: getImprovementTask(gap),
+      priority: gap.gap > 30 ? 'HIGH' : (gap.gap > 15 ? 'MEDIUM' : 'LOW'),
+      effort: gap.gap > 30 ? 'Large' : (gap.gap > 15 ? 'Medium' : 'Small')
+    }));
+
+    const newPlan = {
+      timestamp: new Date().toISOString(),
+      threshold: TARGET_SCORE,
+      iterationCount: iterationCount + 1,
+      baselineScores: currentOverall,
+      enhancements: newEnhancements,
+      predictions: {
+        tasksCount: newEnhancements.length,
+        highPriority: newEnhancements.filter(e => e.priority === 'HIGH').length,
+        mediumPriority: newEnhancements.filter(e => e.priority === 'MEDIUM').length,
+        lowPriority: newEnhancements.filter(e => e.priority === 'LOW').length
+      },
+      confirmed: false,
+      currentTaskIndex: 0
+    };
+    writeFileSync(join(cwd, '.ruvector', 'plan.json'), JSON.stringify(newPlan, null, 2));
+
+    result.newPlan = {
+      iteration: iterationCount + 1,
+      tasks: newEnhancements.length,
+      highPriority: newPlan.predictions.highPriority
+    };
+    result.nextStep = `Iteration ${iterationCount + 1} plan generated. Run kb_first_confirm with confirmed=true to continue.`;
+  }
+
+  return result;
+}
+
+/**
+ * Get improvement task based on gap
+ */
+function getImprovementTask(gap) {
+  if (gap.area === 'KB Quality') {
+    switch (gap.dimension) {
+      case 'Completeness':
+        return `Add more KB entries to reach ${gap.targetScore}% coverage`;
+      case 'Depth':
+        return `Expand KB entries with more detail (target: 2500+ chars each)`;
+      case 'Comprehensiveness':
+        return `Document additional edge cases and exceptions`;
+      case 'Accuracy':
+        return `Add validation tests and verification`;
+      case 'Freshness':
+        return `Update KB content with latest information`;
+      case 'Attribution':
+        return `Add KB-Generated headers to remaining code files`;
+      default:
+        return `Improve ${gap.dimension} to ${gap.targetScore}`;
+    }
+  }
+  return `Complete remaining criteria for ${gap.dimension}`;
+}
+
+/**
+ * Handle MCP tool calls
+ */
+async function handleToolCall(toolName, args) {
+  const cwd = args.projectPath || process.cwd();
+
+  switch (toolName) {
+    case 'kb_first_assess':
+      return await handleAssess(cwd, args);
+    case 'kb_first_plan':
+      return await handlePlan(cwd, args);
+    case 'kb_first_confirm':
+      return await handleConfirm(cwd, args);
+    case 'kb_first_execute':
+      return await handleExecute(cwd, args);
+    case 'kb_first_verify':
+      return await handleVerify(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}` } };
   }
 }
 
 /**
- * Start MCP Server (stdio mode)
+ * Start MCP Server
  */
 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: Granular Score-Driven | Tools: 5 | Dimensions: 6 KB + 12 Phases');
+  console.error('Workflow: Assess → Plan → Confirm → Execute → Verify');
 
-  // 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();
 }