@ankh-studio/ai-enablement 1.0.4 → 2.0.0

package/dist/cli/index.js

@@ -16799,9 +16799,2010 @@ class PersonaFactory {
   }
 }
 
+// src/recommendations/challenger.ts
+class Challenger {
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  challengeRecommendations(recommendations, findings, hypotheses, validationResults) {
+    const assessments = [];
+    for (const recommendation of recommendations) {
+      const assessment = this.challengeRecommendation(recommendation, findings, hypotheses, validationResults);
+      assessments.push(assessment);
+    }
+    return assessments;
+  }
+  challengeRecommendation(recommendation, findings, hypotheses, validationResults) {
+    const criticisms = [];
+    const strengths = [];
+    const alternativeActions = [];
+    const downgradeReasons = [];
+    const genericnessCheck = this.challengeGenericness(recommendation);
+    criticisms.push(...genericnessCheck.criticisms);
+    strengths.push(...genericnessCheck.strengths);
+    downgradeReasons.push(...genericnessCheck.downgradeReasons);
+    const redundancyCheck = this.challengeRedundancy(recommendation, findings, hypotheses);
+    criticisms.push(...redundancyCheck.criticisms);
+    strengths.push(...redundancyCheck.strengths);
+    downgradeReasons.push(...redundancyCheck.downgradeReasons);
+    const evidenceCheck = this.challengeEvidenceSupport(recommendation, findings);
+    criticisms.push(...evidenceCheck.criticisms);
+    strengths.push(...evidenceCheck.strengths);
+    downgradeReasons.push(...evidenceCheck.downgradeReasons);
+    const impactCheck = this.challengeImpactClaims(recommendation);
+    criticisms.push(...impactCheck.criticisms);
+    strengths.push(...impactCheck.strengths);
+    downgradeReasons.push(...impactCheck.downgradeReasons);
+    const priorityCheck = this.challengePriority(recommendation);
+    criticisms.push(...priorityCheck.criticisms);
+    strengths.push(...priorityCheck.strengths);
+    downgradeReasons.push(...priorityCheck.downgradeReasons);
+    const specificityCheck = this.challengeSpecificity(recommendation);
+    criticisms.push(...specificityCheck.criticisms);
+    strengths.push(...specificityCheck.strengths);
+    downgradeReasons.push(...specificityCheck.downgradeReasons);
+    alternativeActions.push(...this.generateAlternatives(recommendation));
+    const { verdict, confidenceAdjustment } = this.determineVerdict(criticisms, strengths, downgradeReasons, recommendation);
+    return {
+      recommendationId: recommendation.id,
+      criticisms,
+      strengths,
+      alternativeActions,
+      downgradeReasons,
+      finalVerdict: verdict,
+      confidenceAdjustment
+    };
+  }
+  challengeGenericness(recommendation) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const title = recommendation.title.toLowerCase();
+    const summary = recommendation.summary.toLowerCase();
+    const whyMatters = recommendation.whyThisMatters.toLowerCase();
+    const genericPatterns = [
+      "improve",
+      "enhance",
+      "optimize",
+      "better",
+      "best practices",
+      "standardize",
+      "add",
+      "implement",
+      "establish"
+    ];
+    const hasGenericLanguage = genericPatterns.some((pattern) => title.includes(pattern) || summary.includes(pattern));
+    const specificPatterns = [
+      "codeowners",
+      "ci/cd",
+      "typescript",
+      "readme",
+      "license",
+      "gitignore",
+      "copilot",
+      "tests",
+      "contributing"
+    ];
+    const hasSpecificLanguage = specificPatterns.some((pattern) => title.includes(pattern) || summary.includes(pattern) || whyMatters.includes(pattern));
+    if (hasGenericLanguage && !hasSpecificLanguage) {
+      result.criticisms.push("Recommendation uses generic language without specific references");
+      result.downgradeReasons.push("Generic advice lacks specificity");
+    }
+    if (hasSpecificLanguage) {
+      result.strengths.push("Recommendation addresses specific tools or files");
+    }
+    const vagueImpactPatterns = [
+      "will improve",
+      "will enhance",
+      "will help",
+      "will make better",
+      "will increase quality"
+    ];
+    const hasVagueImpact = vagueImpactPatterns.some((pattern) => whyMatters.includes(pattern));
+    if (hasVagueImpact) {
+      result.criticisms.push("Impact statement is vague and non-specific");
+      result.downgradeReasons.push("Unclear value proposition");
+    }
+    return result;
+  }
+  challengeRedundancy(recommendation, findings, hypotheses) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const supportingFindings = findings.filter((f) => recommendation.supportingFindings.includes(f.id));
+    for (const finding of supportingFindings) {
+      if (this.calculateSimilarity(recommendation.title, finding.summary) > 0.8) {
+        result.criticisms.push(`Recommendation appears to restate finding: "${finding.summary}"`);
+        result.downgradeReasons.push("Redundant with existing findings");
+        break;
+      }
+    }
+    const supportingHypotheses = hypotheses.filter((h) => recommendation.supportingHypotheses.includes(h.id));
+    if (supportingHypotheses.length === 0 && supportingFindings.length > 0) {
+      result.criticisms.push("Recommendation lacks hypothesis-driven insight");
+      result.downgradeReasons.push("No analytical depth beyond findings");
+    }
+    if (supportingHypotheses.length > 0) {
+      result.strengths.push("Recommendation builds on hypothesis-driven analysis");
+    }
+    return result;
+  }
+  challengeEvidenceSupport(recommendation, findings) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const strongAnchors = recommendation.evidenceAnchors.filter((a) => a.confidence >= 80);
+    const weakAnchors = recommendation.evidenceAnchors.filter((a) => a.confidence < 60);
+    if (weakAnchors.length > strongAnchors.length) {
+      result.criticisms.push("Evidence anchors are predominantly weak");
+      result.downgradeReasons.push("Insufficient evidence support");
+    }
+    if (strongAnchors.length > 0) {
+      result.strengths.push("Strong evidence anchors support recommendation");
+    }
+    for (const anchor of recommendation.evidenceAnchors) {
+      if (anchor.type === "missing" && recommendation.title.toLowerCase().includes("improve")) {
+        result.criticisms.push('Recommendation to "improve" something that doesn\'t exist');
+        result.downgradeReasons.push("Logical inconsistency in evidence");
+        break;
+      }
+    }
+    const anchorTypes = new Set(recommendation.evidenceAnchors.map((a) => a.type));
+    if (anchorTypes.size === 1) {
+      result.criticisms.push("Evidence comes from only one type of source");
+      result.downgradeReasons.push("Limited evidence diversity");
+    }
+    return result;
+  }
+  challengeImpactClaims(recommendation) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const impact = recommendation.expectedImpact;
+    const effort = recommendation.estimatedEffort;
+    const effortValue = { small: 1, medium: 2, large: 3 }[effort.size];
+    const impactValue = { low: 1, medium: 2, high: 3, critical: 4 }[recommendation.priority];
+    if (effortValue > impactValue) {
+      result.criticisms.push("Estimated effort outweighs expected impact");
+      result.downgradeReasons.push("Poor effort-to-impact ratio");
+    }
+    if (effortValue < impactValue) {
+      result.strengths.push("Good effort-to-impact ratio");
+    }
+    if (impact.metrics.length === 0) {
+      result.criticisms.push("No specific impact metrics identified");
+      result.downgradeReasons.push("Impact cannot be measured");
+    } else {
+      result.strengths.push("Specific impact metrics identified");
+    }
+    if (impact.description.length < 50) {
+      result.criticisms.push("Impact description is too brief");
+      result.downgradeReasons.push("Impact not clearly explained");
+    }
+    return result;
+  }
+  challengePriority(recommendation) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const avgEvidenceConfidence = recommendation.evidenceAnchors.reduce((sum, a) => sum + a.confidence, 0) / recommendation.evidenceAnchors.length;
+    const priorityValue = { critical: 4, high: 3, medium: 2, low: 1 }[recommendation.priority];
+    if (priorityValue === 4 && avgEvidenceConfidence < 70) {
+      result.criticisms.push("Critical priority with weak evidence support");
+      result.downgradeReasons.push("Priority overestimated relative to evidence");
+    }
+    if (priorityValue === 1 && avgEvidenceConfidence > 85) {
+      result.criticisms.push("Low priority with strong evidence support");
+      result.downgradeReasons.push("Priority underestimated relative to evidence");
+    }
+    const categoryPriorityMap = {
+      security: "should be high or critical",
+      foundation: "should be medium or high",
+      workflow: "should be medium or high",
+      ai: "should be low or medium",
+      governance: "should be low or medium"
+    };
+    const expectedPriority = categoryPriorityMap[recommendation.category];
+    const actualPriority = recommendation.priority;
+    if (expectedPriority.includes("critical") && actualPriority !== "critical" || expectedPriority.includes("high") && !["critical", "high"].includes(actualPriority) || expectedPriority.includes("low") && !["low", "medium"].includes(actualPriority)) {
+      result.criticisms.push(`Priority seems inappropriate for ${recommendation.category} category`);
+      result.downgradeReasons.push("Category-priority mismatch");
+    }
+    return result;
+  }
+  challengeSpecificity(recommendation) {
+    const result = {
+      criticisms: [],
+      strengths: [],
+      downgradeReasons: []
+    };
+    const fileReferences = recommendation.evidenceAnchors.filter((a) => a.type === "file" || a.type === "missing").map((a) => a.path).filter(Boolean);
+    if (fileReferences.length === 0) {
+      result.criticisms.push("No specific file references in evidence");
+      result.downgradeReasons.push("Lacks concrete file-level guidance");
+    } else {
+      result.strengths.push("References specific files for implementation");
+    }
+    if (recommendation.suggestedNextStep.length < 20) {
+      result.criticisms.push("Suggested next step is too brief");
+      result.downgradeReasons.push("Next step not clearly actionable");
+    }
+    if (!recommendation.implementationHints) {
+      result.criticisms.push("No implementation hints provided");
+      result.downgradeReasons.push("Implementation guidance missing");
+    } else if ((recommendation.implementationHints.commands?.length || 0) > 0 || (recommendation.implementationHints.fileTemplates?.length || 0) > 0) {
+      result.strengths.push("Provides concrete implementation guidance");
+    }
+    return result;
+  }
+  generateAlternatives(recommendation) {
+    const alternatives = [];
+    switch (recommendation.category) {
+      case "security":
+        if (recommendation.title.includes("CODEOWNERS")) {
+          alternatives.push("Consider using branch protection rules instead");
+          alternatives.push("Implement required reviews for sensitive files");
+        }
+        break;
+      case "foundation":
+        if (recommendation.title.includes("README")) {
+          alternatives.push("Add inline code documentation instead");
+          alternatives.push("Create video walkthrough for onboarding");
+        }
+        break;
+      case "workflow":
+        if (recommendation.title.includes("CI/CD")) {
+          alternatives.push("Start with simple pre-commit hooks");
+          alternatives.push("Use external CI service before building internal");
+        }
+        break;
+      case "ai":
+        if (recommendation.title.includes("Copilot")) {
+          alternatives.push("Focus on code comments and documentation first");
+          alternatives.push("Establish coding standards without AI tools");
+        }
+        break;
+    }
+    if (recommendation.estimatedEffort.size === "large") {
+      alternatives.push("Break down into smaller, incremental changes");
+    }
+    if (recommendation.priority === "critical") {
+      alternatives.push("Address underlying issues first before this recommendation");
+    }
+    return alternatives;
+  }
+  determineVerdict(criticisms, strengths, downgradeReasons, recommendation) {
+    const criticismWeight = -10;
+    const strengthWeight = 5;
+    const downgradeWeight = -15;
+    let score = 0;
+    score += criticisms.length * criticismWeight;
+    score += strengths.length * strengthWeight;
+    score += downgradeReasons.length * downgradeWeight;
+    score += (recommendation.confidence.overall - 50) * 0.5;
+    let verdict;
+    let confidenceAdjustment;
+    if (score <= -40) {
+      verdict = "reject";
+      confidenceAdjustment = -50;
+    } else if (score <= -20) {
+      verdict = "downgrade";
+      confidenceAdjustment = -25;
+    } else if (score <= 0) {
+      verdict = "require_human_review";
+      confidenceAdjustment = -10;
+    } else if (downgradeReasons.length > 0) {
+      verdict = "require_human_review";
+      confidenceAdjustment = -5;
+    } else {
+      verdict = "approve";
+      confidenceAdjustment = Math.min(10, score * 0.2);
+    }
+    return { verdict, confidenceAdjustment };
+  }
+  calculateSimilarity(text1, text2) {
+    const words1 = text1.toLowerCase().split(" ");
+    const words2 = text2.toLowerCase().split(" ");
+    const commonWords = words1.filter((word) => words2.includes(word));
+    const totalWords = new Set([...words1, ...words2]).size;
+    return commonWords.length / totalWords;
+  }
+}
+
+// src/recommendations/feedback.ts
+import {readFile as readFile3, writeFile} from "node:fs/promises";
+import {join as join4} from "node:path";
+
+class FeedbackCollector {
+  feedbackPath;
+  feedback = [];
+  constructor(repoPath) {
+    this.feedbackPath = join4(repoPath, ".ai-enablement", "recommendation-feedback.json");
+  }
+  async loadFeedback() {
+    try {
+      const data = await readFile3(this.feedbackPath, "utf-8");
+      this.feedback = JSON.parse(data);
+    } catch (error) {
+      this.feedback = [];
+    }
+  }
+  async saveFeedback() {
+    try {
+      await writeFile(this.feedbackPath, JSON.stringify(this.feedback, null, 2), "utf-8");
+    } catch (error) {
+      console.warn("Could not save feedback file:", error);
+    }
+  }
+  addFeedback(feedback) {
+    const fullFeedback = {
+      ...feedback,
+      timestamp: new Date().toISOString()
+    };
+    this.feedback.push(fullFeedback);
+  }
+  getFeedbackForRecommendation(recommendationId) {
+    return this.feedback.filter((f) => f.recommendationId === recommendationId);
+  }
+  getAllFeedback() {
+    return this.feedback;
+  }
+  getFeedbackStats() {
+    if (this.feedback.length === 0) {
+      return {
+        total: 0,
+        averageScores: {
+          grounded: 0,
+          correct: 0,
+          specific: 0,
+          actionable: 0,
+          valuable: 0
+        },
+        implementationRate: 0
+      };
+    }
+    const scores = this.feedback.reduce((acc, f) => ({
+      grounded: acc.grounded + f.scores.grounded,
+      correct: acc.correct + f.scores.correct,
+      specific: acc.specific + f.scores.specific,
+      actionable: acc.actionable + f.scores.actionable,
+      valuable: acc.valuable + f.scores.valuable
+    }), { grounded: 0, correct: 0, specific: 0, actionable: 0, valuable: 0 });
+    const implemented = this.feedback.filter((f) => f.implemented).length;
+    return {
+      total: this.feedback.length,
+      averageScores: {
+        grounded: scores.grounded / this.feedback.length,
+        correct: scores.correct / this.feedback.length,
+        specific: scores.specific / this.feedback.length,
+        actionable: scores.actionable / this.feedback.length,
+        valuable: scores.valuable / this.feedback.length
+      },
+      implementationRate: implemented / this.feedback.length
+    };
+  }
+  generateFeedbackTemplate(recommendations) {
+    const template = {
+      instructions: "Rate each recommendation on a scale of 0-2 for each criterion",
+      criteria: {
+        grounded: "How well is the recommendation grounded in concrete evidence?",
+        correct: "How accurate is the recommendation for this repository?",
+        specific: "How specific and actionable is the recommendation?",
+        actionable: "How easy is it to implement this recommendation?",
+        valuable: "How valuable would this recommendation be if implemented?"
+      },
+      scale: {
+        0: "Poor - fails completely",
+        1: "Fair - meets expectations",
+        2: "Excellent - exceeds expectations"
+      },
+      recommendations: recommendations.map((rec) => ({
+        recommendationId: rec.id,
+        title: rec.title,
+        category: rec.category,
+        priority: rec.priority,
+        summary: rec.summary,
+        scores: {
+          grounded: 0,
+          correct: 0,
+          specific: 0,
+          actionable: 0,
+          valuable: 0
+        },
+        notes: "",
+        implemented: false,
+        implementationNotes: ""
+      }))
+    };
+    return JSON.stringify(template, null, 2);
+  }
+  async processFeedbackTemplate(templateJson) {
+    try {
+      const template = JSON.parse(templateJson);
+      if (!template.recommendations || !Array.isArray(template.recommendations)) {
+        throw new Error("Invalid template format");
+      }
+      for (const recFeedback of template.recommendations) {
+        this.addFeedback({
+          recommendationId: recFeedback.recommendationId,
+          reviewer: "human",
+          scores: recFeedback.scores,
+          notes: recFeedback.notes,
+          implemented: recFeedback.implemented,
+          implementationNotes: recFeedback.implementationNotes
+        });
+      }
+      await this.saveFeedback();
+    } catch (error) {
+      console.error("Error processing feedback template:", error);
+      throw error;
+    }
+  }
+  getRecommendationQualityTrends() {
+    const trends = {
+      byCategory: {},
+      byPriority: {}
+    };
+    for (const feedback of this.feedback) {
+      const totalScore = Object.values(feedback.scores).reduce((sum, score) => sum + score, 0);
+      const maxScore = Object.values(feedback.scores).length * 2;
+      const normalizedScore = totalScore / maxScore;
+    }
+    return trends;
+  }
+  identifyLowQualityRecommendations(threshold = 0.5) {
+    const lowQualityIds = [];
+    for (const feedback of this.feedback) {
+      const totalScore = Object.values(feedback.scores).reduce((sum, score) => sum + score, 0);
+      const maxScore = Object.values(feedback.scores).length * 2;
+      const normalizedScore = totalScore / maxScore;
+      if (normalizedScore < threshold) {
+        lowQualityIds.push(feedback.recommendationId);
+      }
+    }
+    return [...new Set(lowQualityIds)];
+  }
+  identifyHighValueRecommendations(threshold = 0.8) {
+    const highValueIds = [];
+    for (const feedback of this.feedback) {
+      if (feedback.scores.valuable >= 1.5 && feedback.implemented) {
+        highValueIds.push(feedback.recommendationId);
+      }
+    }
+    return [...new Set(highValueIds)];
+  }
+  generateQualityReport() {
+    const stats = this.getFeedbackStats();
+    const lowQuality = this.identifyLowQualityRecommendations();
+    const highValue = this.identifyHighValueRecommendations();
+    return `
+# Recommendation Quality Report
+
+## Overall Statistics
+- Total recommendations reviewed: ${stats.total}
+- Average scores (0-2 scale):
+  - Grounded: ${stats.averageScores.grounded.toFixed(2)}
+  - Correct: ${stats.averageScores.correct.toFixed(2)}
+  - Specific: ${stats.averageScores.specific.toFixed(2)}
+  - Actionable: ${stats.averageScores.actionable.toFixed(2)}
+  - Valuable: ${stats.averageScores.valuable.toFixed(2)}
+- Implementation rate: ${(stats.implementationRate * 100).toFixed(1)}%
+
+## Quality Insights
+- Low quality recommendations (<50% score): ${lowQuality.length}
+- High value implemented recommendations (>80% valuable): ${highValue.length}
+
+## Recommendations
+- Focus on improving: ${lowQuality.length > 0 ? lowQuality.join(", ") : "None identified"}
+- Replicate success patterns: ${highValue.length > 0 ? highValue.join(", ") : "Insufficient data"}
+
+## Next Steps
+1. Address low-quality recommendation patterns
+2. Analyze high-value recommendations for common characteristics
+3. Use feedback to tune confidence thresholds and validation criteria
+    `.trim();
+  }
+}
+
+// src/recommendations/finding-builder.ts
+class FindingBuilder {
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  buildFindings() {
+    const findings = [];
+    findings.push(...this.buildFoundationFindings());
+    findings.push(...this.buildSecurityFindings());
+    findings.push(...this.buildWorkflowFindings());
+    findings.push(...this.buildAIFindings());
+    findings.push(...this.buildGovernanceFindings());
+    return findings;
+  }
+  buildFoundationFindings() {
+    const findings = [];
+    const { evidence } = this.context;
+    if (!evidence.structure.hasReadme) {
+      findings.push(this.createFinding("found-missing-readme", "foundation", "medium", "Repository lacks README documentation", [
+        {
+          type: "missing",
+          path: "README.md",
+          description: "No README.md found in repository root",
+          confidence: 100
+        }
+      ], ["README.md"]));
+    }
+    if (!evidence.structure.hasLicense) {
+      findings.push(this.createFinding("found-missing-license", "foundation", "high", "Repository lacks license file", [
+        {
+          type: "missing",
+          path: "LICENSE",
+          description: "No LICENSE file found",
+          confidence: 100
+        }
+      ], ["LICENSE"]));
+    }
+    if (evidence.structure.directoryDepth > 8) {
+      findings.push(this.createFinding("found-deep-structure", "foundation", "medium", "Repository has excessively deep directory structure", [
+        {
+          type: "metric",
+          metric: {
+            name: "directory_depth",
+            value: evidence.structure.directoryDepth,
+            threshold: 8
+          },
+          description: `Directory depth is ${evidence.structure.directoryDepth} levels (recommended: \u22648)`,
+          confidence: 90
+        }
+      ], []));
+    }
+    if (!evidence.configuration.hasGitignore) {
+      findings.push(this.createFinding("found-missing-gitignore", "foundation", "high", "Repository lacks .gitignore file", [
+        {
+          type: "missing",
+          path: ".gitignore",
+          description: "No .gitignore file found",
+          confidence: 100
+        }
+      ], [".gitignore"]));
+    }
+    if (!evidence.configuration.hasTypeScript && this.isTypeScriptProject()) {
+      findings.push(this.createFinding("found-typescript-unconfigured", "foundation", "medium", "TypeScript project lacks configuration", [
+        {
+          type: "missing",
+          path: "tsconfig.json",
+          description: "TypeScript files detected but no tsconfig.json found",
+          confidence: 95
+        }
+      ], ["tsconfig.json"]));
+    }
+    return findings;
+  }
+  buildSecurityFindings() {
+    const findings = [];
+    const { copilotFeatures } = this.context;
+    if (!copilotFeatures.githubFeatures.codeowners.found) {
+      findings.push(this.createFinding("found-missing-codeowners", "security", "high", "Repository lacks CODEOWNERS file", [
+        {
+          type: "missing",
+          path: ".github/CODEOWNERS",
+          description: "No CODEOWNERS file found for code ownership rules",
+          confidence: 100
+        }
+      ], [".github/CODEOWNERS"]));
+    }
+    if (this.context.evidence.metrics.dependencyHealth === "poor") {
+      findings.push(this.createFinding("found-poor-dependencies", "security", "high", "Repository has poor dependency health", [
+        {
+          type: "metric",
+          metric: {
+            name: "dependency_health",
+            value: this.context.evidence.metrics.dependencyHealth
+          },
+          description: "Dependency health assessment indicates security or maintenance issues",
+          confidence: 70
+        }
+      ], ["package.json", "yarn.lock", "package-lock.json"]));
+    }
+    return findings;
+  }
+  buildWorkflowFindings() {
+    const findings = [];
+    const { evidence, copilotFeatures } = this.context;
+    if (!evidence.configuration.hasCi) {
+      findings.push(this.createFinding("found-no-ci", "workflow", "high", "Repository lacks CI/CD configuration", [
+        {
+          type: "missing",
+          path: ".github/workflows/",
+          description: "No CI/CD workflows found in .github/workflows/",
+          confidence: 100
+        }
+      ], [".github/workflows/"]));
+    }
+    if (!evidence.configuration.hasTests) {
+      findings.push(this.createFinding("found-no-tests", "workflow", "high", "Repository lacks test configuration", [
+        {
+          type: "missing",
+          description: "No test framework configuration detected",
+          confidence: 90
+        }
+      ], []));
+    }
+    if (!copilotFeatures.githubFeatures.prTemplates.found) {
+      findings.push(this.createFinding("found-no-pr-templates", "workflow", "medium", "Repository lacks PR templates", [
+        {
+          type: "missing",
+          path: ".github/pull_request_template.md",
+          description: "No PR template found for standardizing contributions",
+          confidence: 100
+        }
+      ], [".github/pull_request_template.md"]));
+    }
+    return findings;
+  }
+  buildAIFindings() {
+    const findings = [];
+    const { copilotFeatures } = this.context;
+    if (!copilotFeatures.githubFeatures.copilotInstructions.found) {
+      findings.push(this.createFinding("found-no-copilot-instructions", "ai", "medium", "Repository lacks Copilot instructions", [
+        {
+          type: "missing",
+          path: ".github/copilot-instructions.md",
+          description: "No Copilot instructions found for AI assistance guidance",
+          confidence: 100
+        }
+      ], [".github/copilot-instructions.md"]));
+    }
+    if (copilotFeatures.codePatterns.aiFriendlyComments < 5) {
+      findings.push(this.createFinding("found-low-ai-comments", "ai", "low", "Low AI-friendly comment density", [
+        {
+          type: "metric",
+          metric: {
+            name: "ai_friendly_comments",
+            value: copilotFeatures.codePatterns.aiFriendlyComments,
+            threshold: 5
+          },
+          description: `Only ${copilotFeatures.codePatterns.aiFriendlyComments} AI-friendly comment patterns found`,
+          confidence: 80
+        }
+      ], []));
+    }
+    return findings;
+  }
+  buildGovernanceFindings() {
+    const findings = [];
+    const { evidence } = this.context;
+    if (!evidence.structure.hasContributing) {
+      findings.push(this.createFinding("found-no-contributing", "governance", "medium", "Repository lacks contributing guidelines", [
+        {
+          type: "missing",
+          path: "CONTRIBUTING.md",
+          description: "No CONTRIBUTING.md found for contribution process",
+          confidence: 100
+        }
+      ], ["CONTRIBUTING.md"]));
+    }
+    if (!evidence.structure.hasChangelog) {
+      findings.push(this.createFinding("found-no-changelog", "governance", "low", "Repository lacks changelog", [
+        {
+          type: "missing",
+          path: "CHANGELOG.md",
+          description: "No CHANGELOG.md found for tracking changes",
+          confidence: 100
+        }
+      ], ["CHANGELOG.md"]));
+    }
+    if (evidence.patterns.documentationCoverage < 10) {
+      findings.push(this.createFinding("found-low-docs", "governance", "medium", "Low documentation coverage", [
+        {
+          type: "metric",
+          metric: {
+            name: "documentation_coverage",
+            value: evidence.patterns.documentationCoverage,
+            threshold: 10
+          },
+          description: `Documentation coverage is only ${evidence.patterns.documentationCoverage}%`,
+          confidence: 85
+        }
+      ], []));
+    }
+    return findings;
+  }
+  createFinding(id, category, severity, summary, evidenceAnchors, affectedFiles) {
+    return {
+      id,
+      category,
+      severity,
+      summary,
+      evidenceAnchors,
+      affectedFiles,
+      relatedScores: this.getRelatedScores(category),
+      metadata: {
+        detectionMethod: "deterministic_pattern_match",
+        reproducible: true,
+        timestamp: new Date().toISOString()
+      }
+    };
+  }
+  getRelatedScores(category) {
+    const { scores } = this.context;
+    const scoreMap = {
+      foundation: ["foundation"],
+      security: ["security"],
+      workflow: ["workflow"],
+      ai: ["ai"],
+      governance: ["governance"]
+    };
+    return scoreMap[category].map((scoreCategory) => ({
+      category: scoreCategory,
+      score: scores.breakdown[scoreCategory],
+      impact: "negative"
+    }));
+  }
+  isTypeScriptProject() {
+    const { techStack } = this.context;
+    return techStack.aiReadiness.typescriptUsage || this.context.evidence.configuration.hasTypeScript;
+  }
+}
+
+// src/recommendations/hypothesis-engine.ts
+class HypothesisEngine {
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  generateHypotheses(findings) {
+    const hypotheses = [];
+    const findingsByCategory = this.groupFindingsByCategory(findings);
+    for (const [category, categoryFindings] of Object.entries(findingsByCategory)) {
+      hypotheses.push(...this.generateCategoryHypotheses(category, categoryFindings));
+    }
+    hypotheses.push(...this.generateCrossCategoryHypotheses(findings));
+    return hypotheses;
+  }
+  groupFindingsByCategory(findings) {
+    const grouped = {};
+    for (const finding of findings) {
+      if (!grouped[finding.category]) {
+        grouped[finding.category] = [];
+      }
+      grouped[finding.category].push(finding);
+    }
+    return grouped;
+  }
+  generateCategoryHypotheses(category, findings) {
+    const hypotheses = [];
+    switch (category) {
+      case "security":
+        hypotheses.push(...this.generateSecurityHypotheses(findings));
+        break;
+      case "foundation":
+        hypotheses.push(...this.generateFoundationHypotheses(findings));
+        break;
+      case "workflow":
+        hypotheses.push(...this.generateWorkflowHypotheses(findings));
+        break;
+      case "ai":
+        hypotheses.push(...this.generateAIHypotheses(findings));
+        break;
+      case "governance":
+        hypotheses.push(...this.generateGovernanceHypotheses(findings));
+        break;
+    }
+    return hypotheses;
+  }
+  generateSecurityHypotheses(findings) {
+    const hypotheses = [];
+    const codeownersFinding = findings.find((f) => f.id === "found-missing-codeowners");
+    if (codeownersFinding) {
+      hypotheses.push({
+        id: "hyp-codeowners-velocity",
+        title: "Lack of CODEOWNERS may reduce safe AI-assisted change velocity",
+        description: "Without clear code ownership, AI-assisted changes may lack proper review and approval pathways, potentially reducing the safety and speed of AI-driven development.",
+        category: "security",
+        supportingFindings: [codeownersFinding.id],
+        reasoning: "CODEOWNERS files establish clear ownership and review requirements. In AI-assisted development, this becomes critical for ensuring AI-generated changes receive appropriate human oversight.",
+        confidence: 75,
+        alternativeInterpretations: [
+          "Team may use alternative approval mechanisms",
+          "Repository may not require formal review processes",
+          "Code ownership might be documented elsewhere"
+        ],
+        validationChecks: [
+          {
+            id: "vc-codeowners-alternatives",
+            type: "repo_specificity",
+            description: "Check if alternative approval mechanisms exist",
+            expected: "No alternative approval mechanisms found"
+          },
+          {
+            id: "vc-codeowners-necessity",
+            type: "actionability",
+            description: "Assess if CODEOWNERS is necessary for this repo type",
+            expected: "Repository would benefit from clear ownership"
+          }
+        ],
+        estimatedImpact: "high",
+        estimatedEffort: "small"
+      });
+    }
+    const depFinding = findings.find((f) => f.id === "found-poor-dependencies");
+    if (depFinding) {
+      hypotheses.push({
+        id: "hyp-deps-security-risk",
+        title: "Poor dependency health indicates potential security vulnerabilities",
+        description: "The repository's dependencies show signs of poor maintenance, which could introduce security vulnerabilities and compatibility issues.",
+        category: "security",
+        supportingFindings: [depFinding.id],
+        reasoning: "Poor dependency health often indicates outdated packages with known vulnerabilities or lack of security updates.",
+        confidence: 70,
+        alternativeInterpretations: [
+          "Dependencies may be stable but infrequently updated",
+          "Security scanning might be handled separately",
+          "Repository might use dependency pinning for stability"
+        ],
+        validationChecks: [
+          {
+            id: "vc-deps-actual-vulnerabilities",
+            type: "evidence_strength",
+            description: "Check for actual security vulnerabilities",
+            expected: "Security audit would reveal vulnerabilities"
+          },
+          {
+            id: "vc-deps-update-frequency",
+            type: "repo_specificity",
+            description: "Assess dependency update patterns",
+            expected: "Dependencies are significantly outdated"
+          }
+        ],
+        estimatedImpact: "high",
+        estimatedEffort: "medium"
+      });
+    }
+    return hypotheses;
+  }
+  generateFoundationHypotheses(findings) {
+    const hypotheses = [];
+    const criticalFoundationFindings = findings.filter((f) => f.category === "foundation" && (f.severity === "high" || f.severity === "critical"));
+    if (criticalFoundationFindings.length >= 2) {
+      hypotheses.push({
+        id: "hyp-foundation-immaturity",
+        title: "Multiple foundation issues indicate repository immaturity",
+        description: "The repository shows several foundational gaps that suggest it's in early stages of development or lacks proper project hygiene.",
+        category: "foundation",
+        supportingFindings: criticalFoundationFindings.map((f) => f.id),
+        reasoning: "Multiple foundational issues (README, license, .gitignore, etc.) indicate lack of project maturity and potentially poor developer experience.",
+        confidence: 85,
+        alternativeInterpretations: [
+          "Repository might be intentionally minimal",
+          "Project might be internal or temporary",
+          "Documentation might exist in external systems"
+        ],
+        validationChecks: [
+          {
+            id: "vc-foundation-repo-age",
+            type: "repo_specificity",
+            description: "Check repository age and activity",
+            expected: "Repository is relatively new or inactive"
+          },
+          {
+            id: "vc-foundation-project-type",
+            type: "actionability",
+            description: "Assess if foundation items are needed for this project type",
+            expected: "Project would benefit from standard foundation items"
+          }
+        ],
+        estimatedImpact: "medium",
+        estimatedEffort: "medium"
+      });
+    }
+    const tsFinding = findings.find((f) => f.id === "found-typescript-unconfigured");
+    if (tsFinding) {
+      hypotheses.push({
+        id: "hyp-typescript-consistency",
+        title: "Unconfigured TypeScript may lead to inconsistent code quality",
+        description: "TypeScript files exist without proper configuration, which could lead to inconsistent type checking and reduced developer experience.",
+        category: "foundation",
+        supportingFindings: [tsFinding.id],
+        reasoning: "TypeScript configuration ensures consistent type checking across the project. Without it, developers may have different experiences and code quality may vary.",
+        confidence: 80,
+        alternativeInterpretations: [
+          "TypeScript might be used with default settings",
+          "Configuration might be inherited from parent package",
+          "Project might be in migration phase"
+        ],
+        validationChecks: [
+          {
+            id: "vc-typescript-usage",
+            type: "evidence_strength",
+            description: "Verify actual TypeScript usage extent",
+            expected: "Significant TypeScript files exist"
+          },
+          {
+            id: "vc-typescript-config-impact",
+            type: "actionability",
+            description: "Assess impact of missing configuration",
+            expected: "Configuration would significantly improve development"
+          }
+        ],
+        estimatedImpact: "medium",
+        estimatedEffort: "small"
+      });
+    }
+    return hypotheses;
+  }
+  generateWorkflowHypotheses(findings) {
+    const hypotheses = [];
+    const ciFinding = findings.find((f) => f.id === "found-no-ci");
+    if (ciFinding) {
+      hypotheses.push({
+        id: "hyp-ci-automation-gap",
+        title: "Lack of CI/CD indicates manual deployment and higher risk",
+        description: "Without automated CI/CD, the repository relies on manual processes which increase deployment risk and reduce development velocity.",
+        category: "workflow",
+        supportingFindings: [ciFinding.id],
+        reasoning: "CI/CD automation is standard practice for reliable deployments and quality control. Manual processes are error-prone and slow.",
+        confidence: 90,
+        alternativeInterpretations: [
+          "Repository might be deployed through external systems",
+          "Project might not require automated deployments",
+          "CI/CD might be handled at organizational level"
+        ],
+        validationChecks: [
+          {
+            id: "vc-ci-deployment-frequency",
+            type: "repo_specificity",
+            description: "Check deployment patterns and frequency",
+            expected: "Manual deployments would benefit from automation"
+          },
+          {
+            id: "vc-ci-complexity",
+            type: "actionability",
+            description: "Assess if CI/CD setup is feasible",
+            expected: "Project complexity warrants CI/CD implementation"
+          }
+        ],
+        estimatedImpact: "high",
+        estimatedEffort: "medium"
+      });
+    }
+    const testFinding = findings.find((f) => f.id === "found-no-tests");
+    if (testFinding) {
+      hypotheses.push({
+        id: "hyp-testing-quality-risk",
+        title: "No test configuration indicates quality and maintenance risks",
+        description: "The absence of test configuration suggests minimal automated testing, which increases the risk of bugs and makes changes more dangerous.",
+        category: "workflow",
+        supportingFindings: [testFinding.id],
+        reasoning: "Automated testing is essential for maintaining code quality and enabling safe refactoring. Without tests, changes are risky and maintenance is costly.",
+        confidence: 85,
+        alternativeInterpretations: [
+          "Testing might be done manually or externally",
+          "Project might be simple enough to not need tests",
+          "Tests might exist but not be configured for the test runner"
+        ],
+        validationChecks: [
+          {
+            id: "vc-testing-complexity",
+            type: "repo_specificity",
+            description: "Assess project complexity and testing needs",
+            expected: "Project complexity warrants automated testing"
+          },
+          {
+            id: "vc-testing-implementation",
+            type: "actionability",
+            description: "Evaluate feasibility of implementing tests",
+            expected: "Testing implementation would provide significant value"
+          }
+        ],
+        estimatedImpact: "high",
+        estimatedEffort: "large"
+      });
+    }
+    return hypotheses;
+  }
+  generateAIHypotheses(findings) {
+    const hypotheses = [];
+    const copilotFinding = findings.find((f) => f.id === "found-no-copilot-instructions");
+    if (copilotFinding) {
+      hypotheses.push({
+        id: "hyp-copilot-effectiveness",
+        title: "Lack of Copilot instructions reduces AI assistance effectiveness",
+        description: "Without specific Copilot instructions, AI assistance may not align with project standards and coding practices, reducing its effectiveness.",
+        category: "ai",
+        supportingFindings: [copilotFinding.id],
+        reasoning: "Copilot instructions guide AI tools to generate code that matches project patterns, standards, and preferences. Without them, AI assistance is generic and less valuable.",
+        confidence: 75,
+        alternativeInterpretations: [
+          "Code patterns might be self-documenting",
+          "Team might not use AI assistance extensively",
+          "Instructions might exist in project documentation"
+        ],
+        validationChecks: [
+          {
+            id: "vc-copilot-usage",
+            type: "repo_specificity",
+            description: "Assess AI tool usage in the project",
+            expected: "AI assistance would benefit from specific guidance"
+          },
+          {
+            id: "vc-copilot-patterns",
+            type: "actionability",
+            description: "Evaluate if project has specific patterns worth documenting",
+            expected: "Project has unique patterns that AI should follow"
+          }
+        ],
+        estimatedImpact: "medium",
+        estimatedEffort: "small"
+      });
+    }
+    return hypotheses;
+  }
+  generateGovernanceHypotheses(findings) {
+    const hypotheses = [];
+    const contributingFinding = findings.find((f) => f.id === "found-no-contributing");
+    if (contributingFinding) {
+      hypotheses.push({
+        id: "hyp-contribution-barrier",
+        title: "Missing contributing guidelines creates contribution barriers",
+        description: "Without clear contribution guidelines, potential contributors face uncertainty and may abandon participation, limiting community growth.",
+        category: "governance",
+        supportingFindings: [contributingFinding.id],
+        reasoning: "Contributing guidelines lower the barrier to entry by clearly communicating expectations, processes, and standards for participation.",
+        confidence: 70,
+        alternativeInterpretations: [
+          "Project might not accept external contributions",
+          "Guidelines might be documented in README",
+          "Project might be intentionally closed to contributions"
+        ],
+        validationChecks: [
+          {
+            id: "vc-contribution-activity",
+            type: "repo_specificity",
+            description: "Check if repository accepts external contributions",
+            expected: "Repository would benefit from external contributions"
+          },
+          {
+            id: "vc-contribution-clarity",
+            type: "actionability",
+            description: "Assess if contribution process is unclear",
+            expected: "Contribution process would be clearer with guidelines"
+          }
+        ],
+        estimatedImpact: "medium",
+        estimatedEffort: "small"
+      });
+    }
+    return hypotheses;
+  }
+  generateCrossCategoryHypotheses(findings) {
+    const hypotheses = [];
+    const securityFindings = findings.filter((f) => f.category === "security" && f.severity === "high");
+    const workflowFindings = findings.filter((f) => f.category === "workflow" && f.severity === "high");
+    if (securityFindings.length > 0 && workflowFindings.length > 0) {
+      hypotheses.push({
+        id: "hyp-security-workflow-gap",
+        title: "Security and workflow gaps indicate process immaturity",
+        description: "The combination of security and workflow issues suggests the repository lacks mature development processes that could pose risks for AI-assisted development.",
+        category: "governance",
+        supportingFindings: [
+          ...securityFindings.map((f) => f.id),
+          ...workflowFindings.map((f) => f.id)
+        ],
+        reasoning: "Mature development processes integrate security practices into automated workflows. Gaps in both areas suggest process immaturity.",
+        confidence: 80,
+        alternativeInterpretations: [
+          "Security might be handled through external processes",
+          "Workflow might be intentionally simple",
+          "Project might be in early development phase"
+        ],
+        validationChecks: [
+          {
+            id: "vc-process-maturity",
+            type: "repo_specificity",
+            description: "Assess overall development process maturity",
+            expected: "Process maturity is low and would benefit from improvement"
+          },
+          {
+            id: "vc-ai-readiness",
+            type: "actionability",
+            description: "Evaluate impact on AI-assisted development",
+            expected: "Process gaps would significantly impact AI development safety"
+          }
+        ],
+        estimatedImpact: "high",
+        estimatedEffort: "large"
+      });
+    }
+    return hypotheses;
+  }
+}
+
+// src/recommendations/ranker.ts
+class Ranker {
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  rankRecommendations(validationResults, challengerAssessments, findings, hypotheses) {
+    const promotedValidations = validationResults.filter((v) => v.recommendation === "promote" || v.recommendation === "downgrade");
+    const approvedRecommendations = challengerAssessments.filter((a) => a.finalVerdict === "approve" || a.finalVerdict === "require_human_review");
+    const finalRecommendations = [];
+    for (const validation of promotedValidations) {
+      const hypothesis = hypotheses.find((h) => h.id === validation.hypothesisId);
+      if (!hypothesis)
+        continue;
+      const challengerAssessment = approvedRecommendations.find((a) => a.recommendationId === hypothesis.id);
+      if (challengerAssessment?.finalVerdict === "reject") {
+        continue;
+      }
+      const recommendation = this.createRecommendation(hypothesis, validation, challengerAssessment, findings);
+      finalRecommendations.push(recommendation);
+    }
+    return finalRecommendations.sort((a, b) => {
+      const scoreA = this.calculatePriorityScore(a);
+      const scoreB = this.calculatePriorityScore(b);
+      return scoreB - scoreA;
+    });
+  }
+  createRecommendation(hypothesis, validation, challengerAssessment, findings) {
+    const supportingFindings = findings.filter((f) => hypothesis.supportingFindings.includes(f.id));
+    const evidenceAnchors = supportingFindings.flatMap((f) => f.evidenceAnchors);
+    const affectedFiles = [
+      ...new Set(supportingFindings.flatMap((f) => f.affectedFiles))
+    ];
+    const baseConfidence = validation.confidence;
+    const challengerAdjustment = challengerAssessment?.confidenceAdjustment || 0;
+    const finalConfidence = Math.max(0, Math.min(100, baseConfidence + challengerAdjustment));
+    const needsHumanReview = validation.recommendation === "human_review" || challengerAssessment?.finalVerdict === "require_human_review" || finalConfidence < this.context.config.humanReviewThreshold;
+    const recommendation = {
+      id: `rec-${hypothesis.id}`,
+      title: hypothesis.title,
+      category: hypothesis.category,
+      priority: this.determinePriority(hypothesis, validation, finalConfidence),
+      summary: hypothesis.description,
+      whyThisMatters: this.generateWhyMatters(hypothesis, supportingFindings),
+      evidenceAnchors,
+      affectedFiles,
+      supportingFindings: hypothesis.supportingFindings,
+      supportingHypotheses: [hypothesis.id],
+      validationSummary: {
+        passed: validation.passed,
+        confidence: validation.confidence,
+        blockers: validation.blockers,
+        warnings: validation.warnings
+      },
+      expectedImpact: {
+        description: this.generateImpactDescription(hypothesis),
+        areas: this.determineImpactAreas(hypothesis),
+        metrics: this.generateImpactMetrics(hypothesis)
+      },
+      estimatedEffort: {
+        size: hypothesis.estimatedEffort,
+        timeframes: this.generateTimeframes(hypothesis.estimatedEffort),
+        resources: this.generateResourceList(hypothesis)
+      },
+      confidence: {
+        overall: finalConfidence,
+        evidenceQuality: this.calculateEvidenceQuality(evidenceAnchors),
+        repoSpecificity: this.calculateRepoSpecificity(hypothesis),
+        actionability: this.calculateActionability(hypothesis)
+      },
+      caveats: this.generateCaveats(validation, challengerAssessment),
+      suggestedNextStep: this.generateNextStep(hypothesis, supportingFindings),
+      humanReviewNeeded: needsHumanReview,
+      implementationHints: this.generateImplementationHints(hypothesis, supportingFindings),
+      tags: this.generateTags(hypothesis, supportingFindings),
+      metadata: {
+        generated: new Date().toISOString(),
+        version: "2.0.0",
+        pipeline: [
+          "findings",
+          "hypotheses",
+          "validation",
+          "challenger",
+          "ranking"
+        ]
+      }
+    };
+    return recommendation;
+  }
+  calculatePriorityScore(recommendation) {
+    let score = 0;
+    const priorityScores = { critical: 100, high: 75, medium: 50, low: 25 };
+    score += priorityScores[recommendation.priority];
+    score += recommendation.confidence.overall / 100 * 20;
+    const impactBonus = recommendation.expectedImpact.areas.length * 5;
+    score += impactBonus;
+    const effortPenalties = { small: 0, medium: -5, large: -10 };
+    score += effortPenalties[recommendation.estimatedEffort.size];
+    score += recommendation.confidence.evidenceQuality / 100 * 10;
+    score += recommendation.confidence.repoSpecificity / 100 * 10;
+    const categoryWeights = {
+      security: 1.2,
+      foundation: 1.1,
+      workflow: 1,
+      ai: 0.9,
+      governance: 0.8
+    };
+    score *= categoryWeights[recommendation.category];
+    return Math.round(score);
+  }
+  determinePriority(hypothesis, validation, confidence) {
+    let priority = hypothesis.estimatedImpact;
+    if (confidence < 30) {
+      priority = "low";
+    } else if (confidence < 60 && priority === "critical") {
+      priority = "high";
+    } else if (confidence < 80 && priority === "high") {
+      priority = "medium";
+    }
+    if (validation.warnings.length > 2 && priority !== "low") {
+      const priorities = [
+        "critical",
+        "high",
+        "medium",
+        "low"
+      ];
+      const currentIndex = priorities.indexOf(priority);
+      if (currentIndex < priorities.length - 1) {
+        priority = priorities[currentIndex + 1];
+      }
+    }
+    return priority;
+  }
+  generateWhyMatters(hypothesis, findings) {
+    const categoryReasons = {
+      security: "Security issues pose risks to code integrity, team safety, and organizational compliance. Addressing security gaps is foundational to safe AI-assisted development.",
+      foundation: "Foundation issues affect developer experience, onboarding, and project maintainability. Strong foundations enable scalable, sustainable development.",
+      workflow: "Workflow improvements directly impact development velocity, code quality, and team collaboration. Better workflows reduce friction and increase productivity.",
+      ai: "AI readiness improvements enhance the effectiveness of AI assistance, leading to better code suggestions and more efficient development.",
+      governance: "Governance improvements ensure consistent decision-making, clear contribution processes, and long-term project health."
+    };
+    let baseReason = categoryReasons[hypothesis.category] || "";
+    if (findings.length > 0) {
+      const highSeverityFindings = findings.filter((f) => f.severity === "high" || f.severity === "critical");
+      if (highSeverityFindings.length > 0) {
+        baseReason += ` This is particularly important given the ${highSeverityFindings.length} high-severity issues detected.`;
+      }
+    }
+    return baseReason;
+  }
+  generateImpactDescription(hypothesis) {
+    const impactTemplates = {
+      critical: "Critical impact on {category} posture and overall development safety",
+      high: "Significant improvement in {category} practices and team productivity",
+      medium: "Moderate enhancement to {category} processes and developer experience",
+      low: "Minor improvement to {category} hygiene and best practices"
+    };
+    return impactTemplates[hypothesis.estimatedImpact].replace("{category}", hypothesis.category);
+  }
+  determineImpactAreas(hypothesis) {
+    const areaMap = {
+      security: ["security", "compliance", "risk_management"],
+      foundation: ["developer_experience", "onboarding", "maintainability"],
+      workflow: ["productivity", "code_quality", "collaboration"],
+      ai: ["ai_effectiveness", "code_generation", "development_speed"],
+      governance: [
+        "process_consistency",
+        "contribution_quality",
+        "project_health"
+      ]
+    };
+    return areaMap[hypothesis.category] || [];
+  }
+  generateImpactMetrics(hypothesis) {
+    const metricsMap = {
+      security: ["security_score", "vulnerability_count", "compliance_status"],
+      foundation: [
+        "setup_time",
+        "onboarding_success_rate",
+        "documentation_coverage"
+      ],
+      workflow: ["deployment_frequency", "lead_time", "change_failure_rate"],
+      ai: ["ai_adoption_rate", "code_acceptance_rate", "development_velocity"],
+      governance: [
+        "contribution_rate",
+        "process_adherence",
+        "decision_quality"
+      ]
+    };
+    return metricsMap[hypothesis.category] || [];
+  }
+  generateTimeframes(effort) {
+    const timeframes = {
+      small: {
+        best: "1-2 days",
+        expected: "3-5 days",
+        worst: "1 week"
+      },
+      medium: {
+        best: "1 week",
+        expected: "2-3 weeks",
+        worst: "1 month"
+      },
+      large: {
+        best: "2-3 weeks",
+        expected: "1-2 months",
+        worst: "3 months"
+      }
+    };
+    return timeframes[effort];
+  }
+  generateResourceList(hypothesis) {
+    const baseResources = ["developer_time", "code_review"];
+    const categoryResources = {
+      security: ["security_review", "compliance_check"],
+      foundation: ["documentation_effort", "setup_configuration"],
+      workflow: ["devops_time", "process_design"],
+      ai: ["ai_tool_configuration", "team_training"],
+      governance: ["stakeholder_input", "process_documentation"]
+    };
+    return [
+      ...baseResources,
+      ...categoryResources[hypothesis.category] || []
+    ];
+  }
+  calculateEvidenceQuality(evidenceAnchors) {
+    if (evidenceAnchors.length === 0)
+      return 0;
+    const totalConfidence = evidenceAnchors.reduce((sum, anchor) => sum + anchor.confidence, 0);
+    return Math.round(totalConfidence / evidenceAnchors.length);
+  }
+  calculateRepoSpecificity(hypothesis) {
+    let specificity = 50;
+    if (hypothesis.validationChecks.some((check) => check.description.includes("specific") || check.description.includes("file"))) {
+      specificity += 20;
+    }
+    if (hypothesis.reasoning.includes("this repository") || hypothesis.reasoning.includes("the repository")) {
+      specificity += 15;
+    }
+    if (hypothesis.description.includes("all repositories") || hypothesis.description.includes("every project")) {
+      specificity -= 20;
+    }
+    return Math.max(0, Math.min(100, specificity));
+  }
+  calculateActionability(hypothesis) {
+    let actionability = 50;
+    if (["small", "medium", "large"].includes(hypothesis.estimatedEffort)) {
+      actionability += 15;
+    }
+    if (hypothesis.validationChecks.some((check) => check.type === "actionability")) {
+      actionability += 20;
+    }
+    const actionWords = [
+      "add",
+      "create",
+      "implement",
+      "configure",
+      "establish"
+    ];
+    if (actionWords.some((word) => hypothesis.description.includes(word))) {
+      actionability += 15;
+    }
+    return Math.max(0, Math.min(100, actionability));
+  }
+  generateCaveats(validation, challengerAssessment) {
+    const caveats = [];
+    caveats.push(...validation.warnings);
+    if (challengerAssessment) {
+      caveats.push(...challengerAssessment.criticisms);
+    }
+    if (validation.confidence < 70) {
+      caveats.push("Limited evidence support - verify before implementation");
+    }
+    if (validation.confidence < 50) {
+      caveats.push("Low confidence - requires human validation");
+    }
+    return caveats;
+  }
+  generateNextStep(hypothesis, findings) {
+    const categoryNextSteps = {
+      security: "Conduct security review and implement ownership controls",
+      foundation: "Create foundational files and establish project standards",
+      workflow: "Set up automated workflows and testing infrastructure",
+      ai: "Configure AI tools and establish coding guidelines",
+      governance: "Document processes and establish contribution guidelines"
+    };
+    let nextStep = categoryNextSteps[hypothesis.category] || "Analyze requirements and create implementation plan";
+    const missingFileFindings = findings.filter((f) => f.evidenceAnchors.some((a) => a.type === "missing" && a.path));
+    if (missingFileFindings.length > 0) {
+      const missingFiles = missingFileFindings.flatMap((f) => f.evidenceAnchors.filter((a) => a.type === "missing" && a.path).map((a) => a.path)).slice(0, 2);
+      if (missingFiles.length > 0) {
+        nextStep = `Create ${missingFiles.join(" and ")} to address immediate gaps`;
+      }
+    }
+    return nextStep;
+  }
+  generateImplementationHints(hypothesis, findings) {
+    const hints = {
+      commands: [],
+      fileTemplates: [],
+      references: []
+    };
+    const categoryCommands = {
+      security: ["touch .github/CODEOWNERS", "git add .github/CODEOWNERS"],
+      foundation: ["touch README.md", "touch LICENSE", "touch .gitignore"],
+      workflow: [
+        "mkdir -p .github/workflows",
+        "touch .github/workflows/ci.yml"
+      ],
+      ai: ["touch .github/copilot-instructions.md"],
+      governance: ["touch CONTRIBUTING.md", "touch CHANGELOG.md"]
+    };
+    hints.commands = categoryCommands[hypothesis.category] || [];
+    hints.references = [
+      "https://docs.github.com/en/get-started/quickstart",
+      "https://www.conventionalcommits.org/",
+      "https://semver.org/"
+    ];
+    return hints;
+  }
+  generateTags(hypothesis, findings) {
+    const tags = [hypothesis.category];
+    if (hypothesis.estimatedImpact === "critical") {
+      tags.push("urgent", "security");
+    }
+    if (hypothesis.estimatedEffort === "small") {
+      tags.push("quick-win");
+    } else if (hypothesis.estimatedEffort === "large") {
+      tags.push("significant-effort");
+    }
+    if (hypothesis.supportingFindings.length > 1) {
+      tags.push("well-supported");
+    }
+    return tags;
+  }
+}
+
+// src/recommendations/validator.ts
+class Validator {
+  context;
+  constructor(context) {
+    this.context = context;
+  }
+  validateHypotheses(hypotheses, findings) {
+    const results = [];
+    for (const hypothesis of hypotheses) {
+      const result = this.validateHypothesis(hypothesis, findings);
+      results.push(result);
+    }
+    return results;
+  }
+  validateHypothesis(hypothesis, findings) {
+    const validationChecks = [];
+    const blockers = [];
+    const warnings = [];
+    for (const check of hypothesis.validationChecks) {
+      const result = this.executeValidationCheck(check, hypothesis, findings);
+      validationChecks.push(result);
+      if (!result.passed) {
+        if (this.isBlocker(check.type, result.reason)) {
+          blockers.push(result.reason || "Validation failed");
+        } else {
+          warnings.push(result.reason || "Validation warning");
+        }
+      }
+    }
+    const adjustedConfidence = this.calculateAdjustedConfidence(hypothesis.confidence, validationChecks);
+    const recommendation = this.determineRecommendation(blockers, warnings, adjustedConfidence);
+    return {
+      hypothesisId: hypothesis.id,
+      passed: recommendation === "promote",
+      confidence: adjustedConfidence,
+      validationChecks,
+      blockers,
+      warnings,
+      recommendation
+    };
+  }
+  executeValidationCheck(check, hypothesis, findings) {
+    const resultCheck = { ...check };
+    switch (check.type) {
+      case "evidence_strength":
+        resultCheck.passed = this.validateEvidenceStrength(hypothesis, findings);
+        resultCheck.actual = resultCheck.passed ? "Strong evidence" : "Weak evidence";
+        resultCheck.reason = resultCheck.passed ? "Supporting findings provide strong evidence" : "Supporting findings are weak or insufficient";
+        break;
+      case "repo_specificity":
+        resultCheck.passed = this.validateRepoSpecificity(hypothesis);
+        resultCheck.actual = resultCheck.passed ? "Repo-specific" : "Generic";
+        resultCheck.reason = resultCheck.passed ? "Hypothesis addresses repo-specific characteristics" : "Hypothesis appears generic and could apply to any repo";
+        break;
+      case "actionability":
+        resultCheck.passed = this.validateActionability(hypothesis);
+        resultCheck.actual = resultCheck.passed ? "Actionable" : "Vague";
+        resultCheck.reason = resultCheck.passed ? "Clear, actionable steps can be taken" : "Hypothesis lacks clear actionable steps";
+        break;
+      case "redundancy":
+        resultCheck.passed = this.validateRedundancy(hypothesis, findings);
+        resultCheck.actual = resultCheck.passed ? "Unique" : "Redundant";
+        resultCheck.reason = resultCheck.passed ? "Hypothesis provides unique insight" : "Hypothesis overlaps with other findings/hypotheses";
+        break;
+      case "contradiction":
+        resultCheck.passed = this.validateContradiction(hypothesis, findings);
+        resultCheck.actual = resultCheck.passed ? "Consistent" : "Contradictory";
+        resultCheck.reason = resultCheck.passed ? "Hypothesis is consistent with evidence" : "Hypothesis contradicts available evidence";
+        break;
+    }
+    return resultCheck;
+  }
+  validateEvidenceStrength(hypothesis, findings) {
+    const supportingFindings = findings.filter((f) => hypothesis.supportingFindings.includes(f.id));
+    if (supportingFindings.length === 0) {
+      return false;
+    }
+    let totalEvidenceQuality = 0;
+    let evidenceCount = 0;
+    for (const finding of supportingFindings) {
+      for (const anchor of finding.evidenceAnchors) {
+        totalEvidenceQuality += anchor.confidence;
+        evidenceCount++;
+      }
+    }
+    if (evidenceCount === 0) {
+      return false;
+    }
+    const averageConfidence = totalEvidenceQuality / evidenceCount;
+    return averageConfidence >= 70;
+  }
+  validateRepoSpecificity(hypothesis) {
+    const repoSpecificIndicators = [
+      this.context.repoPath,
+      this.context.evidence.structure.fileCount,
+      this.context.evidence.structure.directoryDepth,
+      this.context.techStack.primaryLanguage,
+      this.context.techStack.frameworks?.length || 0
+    ];
+    const description = hypothesis.description.toLowerCase();
+    const reasoning = hypothesis.reasoning.toLowerCase();
+    const specificIndicators = [
+      "this repository",
+      "the repository",
+      "project shows",
+      "codebase indicates",
+      "analysis reveals",
+      "detected",
+      "found",
+      "shows signs of"
+    ];
+    const hasSpecificLanguage = specificIndicators.some((indicator) => description.includes(indicator) || reasoning.includes(indicator));
+    const genericIndicators = [
+      "all repositories",
+      "every project",
+      "always",
+      "never",
+      "should always"
+    ];
+    const hasGenericLanguage = genericIndicators.some((indicator) => description.includes(indicator) || reasoning.includes(indicator));
+    return hasSpecificLanguage && !hasGenericLanguage;
+  }
+  validateActionability(hypothesis) {
+    const actionableIndicators = [
+      "add",
+      "create",
+      "implement",
+      "configure",
+      "establish",
+      "set up",
+      "enable",
+      "introduce",
+      "define",
+      "document"
+    ];
+    const description = hypothesis.description.toLowerCase();
+    const reasoning = hypothesis.reasoning.toLowerCase();
+    const hasActionableLanguage = actionableIndicators.some((indicator) => description.includes(indicator) || reasoning.includes(indicator));
+    const hasRealisticEffort = ["small", "medium", "large"].includes(hypothesis.estimatedEffort);
+    const hasMeaningfulImpact = ["critical", "high", "medium", "low"].includes(hypothesis.estimatedImpact);
+    return hasActionableLanguage && hasRealisticEffort && hasMeaningfulImpact;
+  }
+  validateRedundancy(hypothesis, findings) {
+    const supportingFindings = findings.filter((f) => hypothesis.supportingFindings.includes(f.id));
+    if (supportingFindings.length === 0) {
+      return true;
+    }
+    const findingSummaries = supportingFindings.map((f) => f.summary.toLowerCase()).join(" ");
+    const hypothesisContent = (hypothesis.description + " " + hypothesis.reasoning).toLowerCase();
+    const commonWords = this.getCommonWords(findingSummaries, hypothesisContent);
+    const similarityRatio = commonWords.length / Math.max(findingSummaries.split(" ").length, 1);
+    return similarityRatio < 0.8;
+  }
+  validateContradiction(hypothesis, findings) {
+    const supportingFindings = findings.filter((f) => hypothesis.supportingFindings.includes(f.id));
+    for (const finding of supportingFindings) {
+      if (finding.severity === "low" && hypothesis.estimatedImpact === "critical") {
+        if (!hypothesis.reasoning.toLowerCase().includes("despite") && !hypothesis.reasoning.toLowerCase().includes("even though") && !hypothesis.reasoning.toLowerCase().includes("potential")) {
+          return false;
+        }
+      }
+      for (const anchor of finding.evidenceAnchors) {
+        if (anchor.type === "missing" && !hypothesis.description.toLowerCase().includes("lack") && !hypothesis.description.toLowerCase().includes("missing") && !hypothesis.description.toLowerCase().includes("without")) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  calculateAdjustedConfidence(originalConfidence, validationChecks) {
+    let adjustedConfidence = originalConfidence;
+    for (const check of validationChecks) {
+      if (!check.passed) {
+        switch (check.type) {
+          case "evidence_strength":
+            adjustedConfidence -= 30;
+            break;
+          case "repo_specificity":
+            adjustedConfidence -= 25;
+            break;
+          case "actionability":
+            adjustedConfidence -= 20;
+            break;
+          case "redundancy":
+            adjustedConfidence -= 15;
+            break;
+          case "contradiction":
+            adjustedConfidence -= 35;
+            break;
+        }
+      }
+    }
+    return Math.max(0, Math.min(100, adjustedConfidence));
+  }
+  determineRecommendation(blockers, warnings, confidence) {
+    if (blockers.length > 0) {
+      return "reject";
+    }
+    if (confidence < 50 && warnings.length > 0) {
+      return "human_review";
+    }
+    if (confidence < 70 && warnings.length > 0) {
+      return "downgrade";
+    }
+    if (confidence >= 70 && warnings.length <= 1) {
+      return "promote";
+    }
+    return "human_review";
+  }
+  isBlocker(checkType, reason) {
+    const blockerTypes = [
+      "contradiction",
+      "evidence_strength"
+    ];
+    if (blockerTypes.includes(checkType)) {
+      return true;
+    }
+    const blockerReasons = [
+      "Supporting findings are weak or insufficient",
+      "Hypothesis contradicts available evidence"
+    ];
+    return blockerReasons.includes(reason || "");
+  }
+  getCommonWords(text1, text2) {
+    const words1 = text1.split(" ").filter((w) => w.length > 3);
+    const words2 = text2.split(" ").filter((w) => w.length > 3);
+    return words1.filter((word) => words2.includes(word));
+  }
+}
+
+// src/recommendations/index.ts
+class RecommendationEngine {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      enableChallenger: true,
+      confidenceThreshold: 50,
+      humanReviewThreshold: 70,
+      enableFeedback: true,
+      ...config
+    };
+  }
+  async generateRecommendations(repoPath, evidence, scores, copilotFeatures, techStack) {
+    const startTime = Date.now();
+    const context = {
+      repoPath,
+      evidence,
+      scores,
+      copilotFeatures,
+      techStack,
+      config: this.config
+    };
+    const findingsResult = await this.runFindingsStage(context);
+    const hypothesesResult = await this.runHypothesesStage(context, findingsResult.data);
+    const validationResult = await this.runValidationStage(context, hypothesesResult.data, findingsResult.data);
+    const challengerResult = await this.runChallengerStage(context, validationResult.data, findingsResult.data, hypothesesResult.data);
+    const rankingResult = await this.runRankingStage(validationResult.data, challengerResult.data, findingsResult.data, hypothesesResult.data);
+    const totalDuration = Date.now() - startTime;
+    const result = {
+      findings: findingsResult.data,
+      hypotheses: hypothesesResult.data,
+      validationResults: validationResult.data,
+      challengerAssessments: challengerResult.data,
+      recommendations: rankingResult.data,
+      pipeline: {
+        findings: findingsResult,
+        hypotheses: hypothesesResult,
+        validation: validationResult,
+        challenger: challengerResult,
+        ranking: rankingResult
+      },
+      metadata: {
+        totalDuration,
+        evidenceCount: this.countEvidenceItems(evidence),
+        confidenceDistribution: this.calculateConfidenceDistribution(rankingResult.data),
+        categoryDistribution: this.calculateCategoryDistribution(rankingResult.data)
+      }
+    };
+    if (this.config.enableFeedback) {
+      await this.saveFeedbackTemplate(repoPath, rankingResult.data);
+    }
+    return result;
+  }
+  async runFindingsStage(context) {
+    const startTime = Date.now();
+    const findingBuilder = new FindingBuilder(context);
+    try {
+      const findings = findingBuilder.buildFindings();
+      return {
+        stage: "findings",
+        success: true,
+        data: findings,
+        errors: [],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: 1,
+          outputCount: findings.length
+        }
+      };
+    } catch (error) {
+      return {
+        stage: "findings",
+        success: false,
+        data: [],
+        errors: [
+          error instanceof Error ? error.message : "Unknown error in findings stage"
+        ],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: 1,
+          outputCount: 0
+        }
+      };
+    }
+  }
+  async runHypothesesStage(context, findings) {
+    const startTime = Date.now();
+    const hypothesisEngine = new HypothesisEngine(context);
+    try {
+      const hypotheses = hypothesisEngine.generateHypotheses(findings);
+      return {
+        stage: "hypotheses",
+        success: true,
+        data: hypotheses,
+        errors: [],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: findings.length,
+          outputCount: hypotheses.length
+        }
+      };
+    } catch (error) {
+      return {
+        stage: "hypotheses",
+        success: false,
+        data: [],
+        errors: [
+          error instanceof Error ? error.message : "Unknown error in hypotheses stage"
+        ],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: findings.length,
+          outputCount: 0
+        }
+      };
+    }
+  }
+  async runValidationStage(context, hypotheses, findings) {
+    const startTime = Date.now();
+    const validator2 = new Validator(context);
+    try {
+      const validationResults = validator2.validateHypotheses(hypotheses, findings);
+      return {
+        stage: "validation",
+        success: true,
+        data: validationResults,
+        errors: [],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: hypotheses.length,
+          outputCount: validationResults.length
+        }
+      };
+    } catch (error) {
+      return {
+        stage: "validation",
+        success: false,
+        data: [],
+        errors: [
+          error instanceof Error ? error.message : "Unknown error in validation stage"
+        ],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: hypotheses.length,
+          outputCount: 0
+        }
+      };
+    }
+  }
+  async runChallengerStage(context, validationResults, findings, hypotheses) {
+    const startTime = Date.now();
+    if (!this.config.enableChallenger) {
+      return {
+        stage: "challenger",
+        success: true,
+        data: [],
+        errors: [],
+        warnings: ["Challenger stage disabled by configuration"],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: validationResults.length,
+          outputCount: 0
+        }
+      };
+    }
+    try {
+      const ranker2 = new Ranker(context);
+      const preliminaryRecommendations = ranker2.rankRecommendations(validationResults, [], findings, hypotheses);
+      const challenger2 = new Challenger(context);
+      const challengerAssessments = challenger2.challengeRecommendations(preliminaryRecommendations, findings, hypotheses, validationResults);
+      return {
+        stage: "challenger",
+        success: true,
+        data: challengerAssessments,
+        errors: [],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: validationResults.length,
+          outputCount: challengerAssessments.length
+        }
+      };
+    } catch (error) {
+      return {
+        stage: "challenger",
+        success: false,
+        data: [],
+        errors: [
+          error instanceof Error ? error.message : "Unknown error in challenger stage"
+        ],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: validationResults.length,
+          outputCount: 0
+        }
+      };
+    }
+  }
+  async runRankingStage(validationResults, challengerAssessments, findings, hypotheses) {
+    const startTime = Date.now();
+    const ranker2 = new Ranker(this.createRankingContext());
+    try {
+      const recommendations = ranker2.rankRecommendations(validationResults, challengerAssessments, findings, hypotheses);
+      return {
+        stage: "ranking",
+        success: true,
+        data: recommendations,
+        errors: [],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: validationResults.length,
+          outputCount: recommendations.length
+        }
+      };
+    } catch (error) {
+      return {
+        stage: "ranking",
+        success: false,
+        data: [],
+        errors: [
+          error instanceof Error ? error.message : "Unknown error in ranking stage"
+        ],
+        warnings: [],
+        metadata: {
+          duration: Date.now() - startTime,
+          inputCount: validationResults.length,
+          outputCount: 0
+        }
+      };
+    }
+  }
+  createRankingContext() {
+    return {
+      repoPath: "",
+      evidence: {},
+      scores: {},
+      copilotFeatures: {},
+      techStack: {},
+      config: this.config
+    };
+  }
+  countEvidenceItems(evidence) {
+    let count = 0;
+    count += Object.values(evidence.structure).filter(Boolean).length;
+    count += Object.values(evidence.configuration).filter(Boolean).length;
+    count += Object.values(evidence.patterns).filter((p) => typeof p === "number" ? p > 0 : Boolean(p)).length;
+    count += Object.values(evidence.metrics).filter((m) => typeof m === "number" ? m > 0 : m !== "fair").length;
+    return count;
+  }
+  calculateConfidenceDistribution(recommendations) {
+    const distribution = { high: 0, medium: 0, low: 0 };
+    for (const rec of recommendations) {
+      if (rec.confidence.overall >= 70)
+        distribution.high++;
+      else if (rec.confidence.overall >= 40)
+        distribution.medium++;
+      else
+        distribution.low++;
+    }
+    return distribution;
+  }
+  calculateCategoryDistribution(recommendations) {
+    const distribution = {};
+    for (const rec of recommendations) {
+      distribution[rec.category] = (distribution[rec.category] || 0) + 1;
+    }
+    return distribution;
+  }
+  async saveFeedbackTemplate(repoPath, recommendations) {
+    try {
+      const feedbackCollector = new FeedbackCollector(repoPath);
+      const template = feedbackCollector.generateFeedbackTemplate(recommendations);
+      const { writeFile: writeFile2 } = await import("node:fs/promises");
+      const { join: join5 } = await import("node:path");
+      const templatePath = join5(repoPath, ".ai-enablement", "feedback-template.json");
+      await writeFile2(templatePath, template, "utf-8");
+      console.log(`\uD83D\uDCDD Feedback template saved to: ${templatePath}`);
+    } catch (error) {
+      console.warn("Could not save feedback template:", error);
+    }
+  }
+  toLegacyRecommendations(v2Recommendations) {
+    return v2Recommendations.map((rec) => ({
+      id: rec.id,
+      title: rec.title,
+      description: rec.summary,
+      priority: rec.priority,
+      category: rec.category,
+      effort: rec.estimatedEffort.size,
+      timeframe: rec.estimatedEffort.timeframes.expected,
+      dependencies: [],
+      evidence: rec.evidenceAnchors.map((a) => a.description)
+    }));
+  }
+}
+
 // src/scanners/copilot-feature-scanner.ts
-import {constants as constants3, access as access3, readFile as readFile3} from "node:fs/promises";
-import {join as join4} from "node:path";
+import {constants as constants3, access as access3, readFile as readFile4} from "node:fs/promises";
+import {join as join5} from "node:path";
 
 // node_modules/simple-git/dist/esm/index.js
 var file_exists = __toESM(require_dist(), 1);
@@ -20867,10 +22868,10 @@ class CopilotFeatureScanner {
       ".github/COPYLOIT_INSTRUCTIONS.md"
     ];
     for (const path of instructionPaths) {
-      const fullPath = join4(repoPath, path);
+      const fullPath = join5(repoPath, path);
       try {
         await access3(fullPath, constants3.R_OK);
-        const content = await readFile3(fullPath, "utf-8");
+        const content = await readFile4(fullPath, "utf-8");
         analysis.githubFeatures.copilotInstructions = {
           found: true,
           path,
@@ -20889,10 +22890,10 @@ class CopilotFeatureScanner {
       "docs/CODEOWNERS"
     ];
     for (const path of codeownersPaths) {
-      const fullPath = join4(repoPath, path);
+      const fullPath = join5(repoPath, path);
       try {
         await access3(fullPath, constants3.R_OK);
-        const content = await readFile3(fullPath, "utf-8");
+        const content = await readFile4(fullPath, "utf-8");
         analysis.githubFeatures.codeowners = {
           found: true,
           path,
@@ -20917,10 +22918,10 @@ class CopilotFeatureScanner {
         ".github/PULL_REQUEST_TEMPLATE.md"
       ];
       for (const path of prTemplatePaths) {
-        const fullPath = join4(repoPath, path);
+        const fullPath = join5(repoPath, path);
         try {
           await access3(fullPath, constants3.R_OK);
-          const content = await readFile3(fullPath, "utf-8");
+          const content = await readFile4(fullPath, "utf-8");
           analysis.githubFeatures.prTemplates = {
             found: true,
             aiFriendly: this.isAiFriendlyTemplate(content)
@@ -20939,7 +22940,7 @@ class CopilotFeatureScanner {
   }
   async scanCodePatterns(repoPath, analysis) {
     try {
-      const tsconfigPath = join4(repoPath, "tsconfig.json");
+      const tsconfigPath = join5(repoPath, "tsconfig.json");
       try {
         await access3(tsconfigPath, constants3.R_OK);
         analysis.codePatterns.typeScriptUsage = true;
@@ -20955,7 +22956,7 @@ class CopilotFeatureScanner {
         "__tests__/"
       ];
       for (const indicator of testIndicators) {
-        const indicatorPath = join4(repoPath, indicator);
+        const indicatorPath = join5(repoPath, indicator);
         try {
           await access3(indicatorPath, indicator.endsWith("/") ? constants3.F_OK : constants3.R_OK);
           analysis.codePatterns.testCoverage = true;
@@ -21280,6 +23281,7 @@ class AssessmentEngine {
   scorer;
   adrGenerator;
   evidenceCollector;
+  recommendationEngine;
   config;
   constructor(config) {
     this.config = {
@@ -21297,6 +23299,7 @@ class AssessmentEngine {
     this.scorer = new ReadinessScorer;
     this.adrGenerator = new ADRGenerator;
     this.evidenceCollector = new EvidenceCollector;
+    this.recommendationEngine = new RecommendationEngine(this.config.recommendationConfig);
   }
   async execute() {
     const startTime = Date.now();
@@ -21314,7 +23317,71 @@ class AssessmentEngine {
         evidence
       });
       console.log("\uD83C\uDFAF Scoring complete, generating recommendations...");
-      const recommendations = this.config.includeRecommendations ? await this.generateRecommendations(scores, copilotFeatures, evidence) : [];
+      let recommendations2 = [];
+      let recommendationEngine;
+      if (this.config.includeRecommendations) {
+        console.log("\uD83D\uDE80 Using Recommendation Engine V2...");
+        recommendationEngine = await this.recommendationEngine.generateRecommendations(this.config.repoPath, evidence, scores, copilotFeatures, techStack);
+        recommendations2 = this.recommendationEngine.toLegacyRecommendations(recommendationEngine.recommendations);
+        console.log(`\u2705 V2 Engine generated ${recommendationEngine.recommendations.length} recommendations`);
+      } else {
+        recommendationEngine = {
+          findings: [],
+          hypotheses: [],
+          validationResults: [],
+          challengerAssessments: [],
+          recommendations: [],
+          pipeline: {
+            findings: {
+              stage: "findings",
+              success: true,
+              data: [],
+              errors: [],
+              warnings: [],
+              metadata: { duration: 0, inputCount: 0, outputCount: 0 }
+            },
+            hypotheses: {
+              stage: "hypotheses",
+              success: true,
+              data: [],
+              errors: [],
+              warnings: [],
+              metadata: { duration: 0, inputCount: 0, outputCount: 0 }
+            },
+            validation: {
+              stage: "validation",
+              success: true,
+              data: [],
+              errors: [],
+              warnings: [],
+              metadata: { duration: 0, inputCount: 0, outputCount: 0 }
+            },
+            challenger: {
+              stage: "challenger",
+              success: true,
+              data: [],
+              errors: [],
+              warnings: [],
+              metadata: { duration: 0, inputCount: 0, outputCount: 0 }
+            },
+            ranking: {
+              stage: "ranking",
+              success: true,
+              data: [],
+              errors: [],
+              warnings: [],
+              metadata: { duration: 0, inputCount: 0, outputCount: 0 }
+            }
+          },
+          metadata: {
+            totalDuration: 0,
+            evidenceCount: 0,
+            confidenceDistribution: { high: 0, medium: 0, low: 0 },
+            categoryDistribution: {}
+          }
+        };
+        recommendations2 = [];
+      }
       let personaInsights;
       if (this.config.persona) {
         console.log("\uD83E\uDD16 Generating persona insights...");
@@ -21328,7 +23395,7 @@ class AssessmentEngine {
           copilotFeatures,
           techStack,
           evidence,
-          recommendations,
+          recommendations: recommendations2,
           structuredInsights: personaInsights?.structuredInsights
         });
       }
@@ -21337,7 +23404,7 @@ class AssessmentEngine {
         metadata: {
           timestamp: new Date().toISOString(),
           repository: this.config.repoPath,
-          version: "1.0.0",
+          version: "2.0.0",
           duration
         },
         analysis: {
@@ -21346,7 +23413,8 @@ class AssessmentEngine {
           evidence
         },
         scores,
-        recommendations
+        recommendations: recommendations2,
+        recommendationEngine
       };
       if (personaInsights) {
         result.personaInsights = personaInsights;
@@ -21362,9 +23430,9 @@ class AssessmentEngine {
     }
   }
   async generateRecommendations(scores, features, evidence) {
-    const recommendations = [];
+    const recommendations2 = [];
     if (scores.repoReadiness < 70) {
-      recommendations.push({
+      recommendations2.push({
         id: "found-001",
         title: "Improve Repository Structure",
         description: "Standardize repository structure and add essential configuration files",
@@ -21377,7 +23445,7 @@ class AssessmentEngine {
       });
     }
     if (!features.githubFeatures.codeowners.found) {
-      recommendations.push({
+      recommendations2.push({
         id: "sec-001",
         title: "Add CODEOWNERS File",
         description: "Define code ownership for better security and review processes",
@@ -21390,7 +23458,7 @@ class AssessmentEngine {
       });
     }
     if (!features.githubFeatures.copilotInstructions.found) {
-      recommendations.push({
+      recommendations2.push({
         id: "ai-001",
         title: "Add Copilot Instructions",
         description: "Create Copilot instructions to guide AI assistance in your repository",
@@ -21403,7 +23471,7 @@ class AssessmentEngine {
       });
     }
     if (scores.orgReadiness < 60) {
-      recommendations.push({
+      recommendations2.push({
         id: "gov-001",
         title: "Establish Governance Processes",
         description: "Implement clear processes for code review, testing, and deployment",
@@ -21415,7 +23483,7 @@ class AssessmentEngine {
         evidence: this.extractEvidence(evidence, ["governance", "process"])
       });
     }
-    return recommendations.sort((a, b) => {
+    return recommendations2.sort((a, b) => {
       const priorityOrder = { high: 3, medium: 2, low: 1 };
       return priorityOrder[b.priority] - priorityOrder[a.priority];
     });
@@ -21440,7 +23508,7 @@ class AssessmentEngine {
         metadata: {
           timestamp: new Date().toISOString(),
           repository: this.config.repoPath,
-          version: "1.0.0",
+          version: "2.0.0",
           duration: 0
         },
         analysis: {
@@ -21538,9 +23606,11 @@ function displayResults(result, persona) {
   console.log(import_chalk.default.gray(`Repository: ${result.metadata.repository}`));
   console.log(import_chalk.default.gray(`Assessed: ${result.metadata.timestamp}`));
   console.log(import_chalk.default.gray(`Duration: ${result.metadata.duration}ms`));
+  console.log(import_chalk.default.gray(`Version: ${result.metadata.version}`));
   console.log(import_chalk.default.gray(`Persona: ${persona}\n`));
   displayScores(result.scores);
   displayRecommendations(result.recommendations);
+  displayRecommendationEngine(result.recommendationEngine);
   if (result.personaInsights) {
     displayPersonaInsights(result.personaInsights);
   }
@@ -21581,13 +23651,52 @@ function displayScores(scores) {
   });
   console.log(import_chalk.default.gray(`Confidence: ${scores.confidence}\n`));
 }
-function displayRecommendations(recommendations) {
-  if (recommendations.length === 0) {
+function displayRecommendationEngine(engineResult) {
+  console.log(import_chalk.default.bold.blue(`
+\uD83D\uDE80 Recommendation Engine Results`));
+  console.log(import_chalk.default.gray(`Pipeline Duration: ${engineResult.metadata.totalDuration}ms`));
+  console.log(import_chalk.default.gray(`Evidence Items: ${engineResult.metadata.evidenceCount}`));
+  console.log(import_chalk.default.gray(`Findings: ${engineResult.findings.length}`));
+  console.log(import_chalk.default.gray(`Hypotheses: ${engineResult.hypotheses.length}`));
+  console.log(import_chalk.default.gray(`Final Recommendations: ${engineResult.recommendations.length}\n`));
+  if (engineResult.recommendations.length === 0) {
+    console.log(import_chalk.default.green("\u2705 No recommendations - repository is well prepared!"));
+    return;
+  }
+  const groupedRecs = engineResult.recommendations.reduce((groups, rec) => {
+    if (!groups[rec.priority])
+      groups[rec.priority] = [];
+    groups[rec.priority].push(rec);
+    return groups;
+  }, {});
+  ["critical", "high", "medium", "low"].forEach((priority) => {
+    const recs = groupedRecs[priority];
+    if (recs && recs.length > 0) {
+      const priorityColor = priority === "critical" ? import_chalk.default.red : priority === "high" ? import_chalk.default.red : priority === "medium" ? import_chalk.default.yellow : import_chalk.default.gray;
+      console.log(import_chalk.default.bold(`\n${priorityColor(priority.toUpperCase())} PRIORITY:`));
+      recs.forEach((rec) => {
+        console.log(`  ${import_chalk.default.bold(rec.title)} (${rec.category})`);
+        console.log(`  ${import_chalk.default.gray(rec.summary)}`);
+        console.log(`  ${import_chalk.default.blue(`Confidence: ${rec.confidence.overall}% | Evidence: ${rec.evidenceAnchors.length} anchors`)}`);
+        if (rec.humanReviewNeeded) {
+          console.log(`  ${import_chalk.default.yellow("\u26A0\uFE0F  Requires human review")}`);
+        }
+        console.log(`  ${import_chalk.default.cyan(`Next: ${rec.suggestedNextStep}`)}`);
+        if (rec.caveats.length > 0) {
+          console.log(`  ${import_chalk.default.hex("#FFA500")(`Caveats: ${rec.caveats.slice(0, 2).join("; ")}`)}`);
+        }
+        console.log("");
+      });
+    }
+  });
+}
+function displayRecommendations(recommendations2) {
+  if (recommendations2.length === 0) {
     console.log(import_chalk.default.green("\u2705 No recommendations needed - repository is well prepared!"));
     return;
   }
   console.log(import_chalk.default.bold.blue("\uD83C\uDFAF Recommendations"));
-  const groupedRecs = recommendations.reduce((groups, rec) => {
+  const groupedRecs = recommendations2.reduce((groups, rec) => {
     if (!groups[rec.priority])
       groups[rec.priority] = [];
     groups[rec.priority].push(rec);
@@ -21671,9 +23780,352 @@ function getMaturityStatus(level) {
     return import_chalk.default.hex("#FFA500")("\uD83D\uDD36 Basic");
   return import_chalk.default.red("\u274C Initial");
 }
+async function generateRoadmap(result, options) {
+  const timeframe = parseInt(options.timeframe) || 12;
+  const pace = options.pace || "moderate";
+  const paceMultipliers = {
+    aggressive: 0.75,
+    moderate: 1,
+    conservative: 1.5
+  };
+  const adjustedTimeframe = timeframe * paceMultipliers[pace];
+  const groupedRecs = result.recommendations.reduce((groups, rec) => {
+    const key = `${rec.category}-${rec.priority}`;
+    if (!groups[key])
+      groups[key] = [];
+    groups[key].push(rec);
+    return groups;
+  }, {});
+  const phases = createPhases(result.scores.overallMaturity, groupedRecs, adjustedTimeframe);
+  const roadmap = {
+    metadata: {
+      repository: result.metadata.repository,
+      generated: new Date().toISOString(),
+      timeframe,
+      pace,
+      persona: options.persona || "consultant"
+    },
+    summary: {
+      currentMaturity: result.scores.overallMaturity,
+      targetMaturity: Math.min(8, result.scores.overallMaturity + 3),
+      totalPhases: phases.length,
+      estimatedDuration: `${Math.ceil(adjustedTimeframe)} months`,
+      criticalPath: getCriticalPath(phases)
+    },
+    phases,
+    successMetrics: options.includeMetrics ? generateSuccessMetrics(phases) : { kpis: [], milestones: [] }
+  };
+  return roadmap;
+}
+function createPhases(currentMaturity, groupedRecs, timeframe) {
+  const phases = [];
+  if (currentMaturity < 6) {
+    const foundationRecs = Object.entries(groupedRecs).filter(([key]) => key.includes("foundation") || key.includes("high")).flatMap(([, recs]) => recs);
+    phases.push({
+      id: "foundation",
+      name: "Foundation & Infrastructure",
+      description: "Establish the technical and organizational foundation for AI enablement",
+      duration: `${Math.ceil(timeframe * 0.25)} months`,
+      priority: "critical",
+      objectives: [
+        "Establish robust development infrastructure",
+        "Implement security and governance frameworks",
+        "Build foundational AI tooling and workflows"
+      ],
+      actions: foundationRecs.map((rec) => ({
+        title: rec.title,
+        description: rec.description,
+        effort: rec.effort,
+        timeframe: rec.timeframe,
+        dependencies: rec.dependencies,
+        expectedOutcomes: [
+          `Improved ${rec.category} maturity`,
+          "Reduced technical debt",
+          "Enhanced team productivity"
+        ]
+      })),
+      risks: [
+        {
+          description: "Resource constraints delaying foundation work",
+          mitigation: "Phase critical items, secure executive sponsorship",
+          probability: "medium",
+          impact: "high"
+        }
+      ]
+    });
+  }
+  if (currentMaturity < 7) {
+    const aiRecs = Object.entries(groupedRecs).filter(([key]) => key.includes("ai") || key.includes("workflow")).flatMap(([, recs]) => recs);
+    phases.push({
+      id: "integration",
+      name: "AI Integration & Adoption",
+      description: "Integrate AI tools into development workflows and build team capabilities",
+      duration: `${Math.ceil(timeframe * 0.35)} months`,
+      priority: "high",
+      objectives: [
+        "Deploy AI-powered development tools",
+        "Train teams on AI-assisted workflows",
+        "Establish AI governance and best practices"
+      ],
+      actions: aiRecs.map((rec) => ({
+        title: rec.title,
+        description: rec.description,
+        effort: rec.effort,
+        timeframe: rec.timeframe,
+        dependencies: rec.dependencies,
+        expectedOutcomes: [
+          "Increased developer productivity",
+          "Improved code quality",
+          "Enhanced innovation capacity"
+        ]
+      })),
+      risks: [
+        {
+          description: "Team resistance to AI adoption",
+          mitigation: "Comprehensive training, demonstrate quick wins",
+          probability: "medium",
+          impact: "medium"
+        }
+      ]
+    });
+  }
+  phases.push({
+    id: "optimization",
+    name: "Optimization & Scale",
+    description: "Optimize AI workflows and scale successful practices across the organization",
+    duration: `${Math.ceil(timeframe * 0.4)} months`,
+    priority: "medium",
+    objectives: [
+      "Optimize AI tooling and workflows",
+      "Scale successful practices organization-wide",
+      "Establish continuous improvement processes"
+    ],
+    actions: [
+      {
+        title: "Implement Advanced AI Analytics",
+        description: "Deploy sophisticated AI-powered analytics for development insights",
+        effort: "High",
+        timeframe: "2-3 months",
+        dependencies: [
+          "Foundation & Infrastructure",
+          "AI Integration & Adoption"
+        ],
+        expectedOutcomes: [
+          "Data-driven decision making",
+          "Predictive insights for development",
+          "Continuous performance monitoring"
+        ],
+        successMetrics: [
+          "50% reduction in bug detection time",
+          "30% improvement in deployment frequency",
+          "25% reduction in technical debt accumulation"
+        ]
+      },
+      {
+        title: "Establish AI Center of Excellence",
+        description: "Create a centralized team to drive AI innovation and best practices",
+        effort: "Medium",
+        timeframe: "1-2 months",
+        dependencies: ["AI Integration & Adoption"],
+        expectedOutcomes: [
+          "Centralized AI expertise",
+          "Standardized best practices",
+          "Innovation incubation"
+        ]
+      }
+    ],
+    risks: [
+      {
+        description: "Scaling challenges as organization grows",
+        mitigation: "Build scalable processes, document best practices",
+        probability: "low",
+        impact: "medium"
+      }
+    ]
+  });
+  return phases;
+}
+function getCriticalPath(phases) {
+  return phases.filter((phase) => phase.priority === "critical" || phase.priority === "high").map((phase) => phase.name);
+}
+function generateSuccessMetrics(phases) {
+  return {
+    kpis: [
+      {
+        name: "Developer Productivity",
+        description: "Measure of developer output and efficiency",
+        target: "+30% in 6 months",
+        measurement: "Lines of code per developer, deployment frequency"
+      },
+      {
+        name: "Code Quality",
+        description: "Overall codebase health and maintainability",
+        target: "Reduce bugs by 40%",
+        measurement: "Bug density, test coverage, code review metrics"
+      },
+      {
+        name: "AI Adoption Rate",
+        description: "Percentage of team actively using AI tools",
+        target: "80% adoption in 3 months",
+        measurement: "Tool usage analytics, survey responses"
+      }
+    ],
+    milestones: [
+      {
+        name: "Foundation Complete",
+        date: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString().split("T")[0],
+        criteria: [
+          "All infrastructure recommendations implemented",
+          "Security frameworks in place",
+          "Team training completed"
+        ]
+      },
+      {
+        name: "AI Integration Milestone",
+        date: new Date(Date.now() + 180 * 24 * 60 * 60 * 1000).toISOString().split("T")[0],
+        criteria: [
+          "AI tools deployed to all teams",
+          "70% adoption rate achieved",
+          "Productivity gains measurable"
+        ]
+      }
+    ]
+  };
+}
+function displayRoadmapSummary(roadmap) {
+  console.log(import_chalk.default.bold.blue(`
+\uD83D\uDEE3\uFE0F  AI Enablement Roadmap`));
+  console.log(import_chalk.default.gray(`Repository: ${roadmap.metadata.repository}`));
+  console.log(import_chalk.default.gray(`Generated: ${new Date(roadmap.metadata.generated).toLocaleDateString()}`));
+  console.log(import_chalk.default.gray(`Timeframe: ${roadmap.summary.estimatedDuration}`));
+  console.log(import_chalk.default.gray(`Pace: ${roadmap.metadata.pace}\n`));
+  console.log(import_chalk.default.bold("\uD83D\uDCCA Maturity Progression"));
+  console.log(`Current: ${import_chalk.default.yellow(roadmap.summary.currentMaturity)}/8 \u2192 Target: ${import_chalk.default.green(roadmap.summary.targetMaturity)}/8`);
+  console.log(`Total Phases: ${roadmap.summary.totalPhases}`);
+  console.log(`Critical Path: ${roadmap.summary.criticalPath.join(" \u2192 ")}\n`);
+  console.log(import_chalk.default.bold("\uD83C\uDFAF Phases Overview"));
+  roadmap.phases.forEach((phase, index) => {
+    const priorityColor = phase.priority === "critical" ? import_chalk.default.red : phase.priority === "high" ? import_chalk.default.yellow : phase.priority === "medium" ? import_chalk.default.blue : import_chalk.default.gray;
+    console.log(`\n${index + 1}. ${import_chalk.default.bold(phase.name)} ${priorityColor(`(${phase.priority.toUpperCase()})`)}`);
+    console.log(`   ${import_chalk.default.gray(phase.description)}`);
+    console.log(`   ${import_chalk.default.blue(`Duration: ${phase.duration} | Actions: ${phase.actions.length}`)}`);
+    phase.objectives.slice(0, 2).forEach((obj) => {
+      console.log(`   \u2022 ${import_chalk.default.white(obj)}`);
+    });
+  });
+  if (roadmap.successMetrics.kpis.length > 0) {
+    console.log(import_chalk.default.bold(`
+\uD83D\uDCC8 Key Success Metrics`));
+    roadmap.successMetrics.kpis.slice(0, 3).forEach((kpi) => {
+      console.log(`\u2022 ${import_chalk.default.bold(kpi.name)}: ${kpi.target}`);
+    });
+  }
+}
+async function saveRoadmap(roadmap, outputPath, format) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  await fs.mkdir(outputPath, { recursive: true });
+  if (format === "markdown" || format === "both") {
+    const markdown = generateMarkdownRoadmap(roadmap);
+    await fs.writeFile(path.join(outputPath, "roadmap.md"), markdown, "utf-8");
+    console.log(import_chalk.default.green(`\uD83D\uDCC4 Roadmap saved to: ${path.join(outputPath, "roadmap.md")}`));
+  }
+  if (format === "json" || format === "both") {
+    await fs.writeFile(path.join(outputPath, "roadmap.json"), JSON.stringify(roadmap, null, 2), "utf-8");
+    console.log(import_chalk.default.green(`\uD83D\uDCC4 Roadmap saved to: ${path.join(outputPath, "roadmap.json")}`));
+  }
+}
+function generateMarkdownRoadmap(roadmap) {
+  let markdown = `# AI Enablement Roadmap
+
+**Repository:** ${roadmap.metadata.repository}  
+**Generated:** ${new Date(roadmap.metadata.generated).toLocaleDateString()}  
+**Timeframe:** ${roadmap.summary.estimatedDuration} (${roadmap.metadata.pace} pace)  
+**Persona:** ${roadmap.metadata.persona}
+
+## Executive Summary
+
+- **Current Maturity:** ${roadmap.summary.currentMaturity}/8
+- **Target Maturity:** ${roadmap.summary.targetMaturity}/8
+- **Total Phases:** ${roadmap.summary.totalPhases}
+- **Critical Path:** ${roadmap.summary.criticalPath.join(" \u2192 ")}
+
+`;
+  roadmap.phases.forEach((phase, index) => {
+    markdown += `## Phase ${index + 1}: ${phase.name}
+
+**Priority:** ${phase.priority.toUpperCase()}  
+**Duration:** ${phase.duration}
+
+${phase.description}
+
+### Objectives
+`;
+    phase.objectives.forEach((obj) => {
+      markdown += `- ${obj}\n`;
+    });
+    markdown += `\n### Actions\n`;
+    phase.actions.forEach((action) => {
+      markdown += `#### ${action.title}
+
+**Effort:** ${action.effort} | **Timeframe:** ${action.timeframe}
+
+${action.description}
+
+**Expected Outcomes:**
+`;
+      action.expectedOutcomes.forEach((outcome) => {
+        markdown += `- ${outcome}\n`;
+      });
+      if (action.dependencies.length > 0) {
+        markdown += `\n**Dependencies:** ${action.dependencies.join(", ")}\n`;
+      }
+      if (action.successMetrics && action.successMetrics.length > 0) {
+        markdown += `\n**Success Metrics:**\n`;
+        action.successMetrics.forEach((metric) => {
+          markdown += `- ${metric}\n`;
+        });
+      }
+      markdown += "\n";
+    });
+    if (phase.risks.length > 0) {
+      markdown += `### Risks & Mitigations\n`;
+      phase.risks.forEach((risk) => {
+        markdown += `- **${risk.description}** (${risk.probability} probability, ${risk.impact} impact)\n`;
+        markdown += `  - *Mitigation:* ${risk.mitigation}\n`;
+      });
+      markdown += "\n";
+    }
+  });
+  if (roadmap.successMetrics.kpis.length > 0) {
+    markdown += `## Success Metrics\n\n### Key Performance Indicators\n`;
+    roadmap.successMetrics.kpis.forEach((kpi) => {
+      markdown += `#### ${kpi.name}
+
+**Target:** ${kpi.target}
+
+${kpi.description}
+
+**Measurement:** ${kpi.measurement}
+
+`;
+    });
+    markdown += `### Milestones\n`;
+    roadmap.successMetrics.milestones.forEach((milestone) => {
+      markdown += `#### ${milestone.name} (${milestone.date})
+
+`;
+      milestone.criteria.forEach((criteria) => {
+        markdown += `- ${criteria}\n`;
+      });
+      markdown += "\n";
+    });
+  }
+  return markdown;
+}
 var program2 = new Command;
 program2.name("ai-enablement").description("AI Enablement Platform - Analyze repository readiness for AI adoption").version("1.0.0");
-program2.command("analyze").description("Analyze repository for AI enablement readiness").argument("<repo-path>", "Path to the repository to analyze").option("-o, --output <path>", "Output directory for results").option("-f, --format <format>", "Output format (json, adr, markdown)", "json").option("--no-recommendations", "Skip recommendations generation").option("--no-adr", "Skip ADR generation").option("--persona <type>", "Analysis persona (consultant, evangelist, team-lead)", "consultant").option("--llm-coalescing", "Enable LLM coalescing with adversarial validation").option("--adversarial-validation", "Enable adversarial validation (default: enabled with LLM)").action(async (repoPath, options) => {
+program2.command("analyze").description("Analyze repository for AI enablement readiness").argument("<repo-path>", "Path to the repository to analyze").option("-o, --output <path>", "Output directory for results").option("-f, --format <format>", "Output format (json, adr, markdown)", "json").option("--no-recommendations", "Skip recommendations generation").option("--no-adr", "Skip ADR generation").option("--persona <type>", "Analysis persona (consultant, evangelist, team-lead)", "consultant").option("--llm-coalescing", "Enable LLM coalescing with adversarial validation").option("--adversarial-validation", "Enable adversarial validation (default: enabled with LLM)").option("--challenger", "Enable challenger pass for recommendation validation").option("--confidence-threshold <number>", "Minimum confidence threshold for recommendations", "50").option("--human-review-threshold <number>", "Confidence threshold requiring human review", "70").action(async (repoPath, options) => {
   try {
     const spinner = import_ora.default("Initializing AI Enablement Assessment...").start();
     const config = {
@@ -21684,7 +24136,13 @@ program2.command("analyze").description("Analyze repository for AI enablement re
       outputFormat: options.format,
       persona: options.persona,
       enableLLMCoalescing: options.llmCoalescing || false,
-      enableAdversarialValidation: options.adversarialValidation || options.llmCoalescing
+      enableAdversarialValidation: options.adversarialValidation || options.llmCoalescing,
+      recommendationConfig: {
+        enableChallenger: options.challenger || true,
+        confidenceThreshold: parseInt(options.confidenceThreshold) || 50,
+        humanReviewThreshold: parseInt(options.humanReviewThreshold) || 70,
+        enableFeedback: true
+      }
     };
     const engine = new AssessmentEngine(config);
     spinner.text = "Analyzing repository...";
@@ -21729,14 +24187,14 @@ program2.command("recommend").description("Generate recommendations for a reposi
     const spinner = import_ora.default("Generating recommendations...").start();
     const result = await engine.execute();
     spinner.succeed("Recommendations generated!");
-    let recommendations = result.recommendations;
+    let recommendations2 = result.recommendations;
     if (options.priority) {
-      recommendations = recommendations.filter((r) => r.priority === options.priority);
+      recommendations2 = recommendations2.filter((r) => r.priority === options.priority);
     }
     if (options.category) {
-      recommendations = recommendations.filter((r) => r.category === options.category);
+      recommendations2 = recommendations2.filter((r) => r.category === options.category);
     }
-    displayRecommendations(recommendations);
+    displayRecommendations(recommendations2);
   } catch (error) {
     console.error(import_chalk.default.red("\u274C Recommendation generation failed:"), error);
     process.exit(1);
@@ -21765,6 +24223,29 @@ program2.command("adr").description("Generate Architecture Decision Record for A
     process.exit(1);
   }
 });
+program2.command("path").description("Generate strategic AI enablement roadmap with phased approach").argument("<repo-path>", "Path to the repository to analyze").option("-o, --output <path>", "Output directory for roadmap files").option("--format <format>", "Output format (markdown, json, both)", "markdown").option("--persona <type>", "Analysis persona (consultant, evangelist, team-lead)", "consultant").option("--timeframe <months>", "Target timeframe for full enablement in months", "12").option("--pace <speed>", "Implementation pace (aggressive, moderate, conservative)", "moderate").option("--include-metrics", "Include success metrics and KPIs").action(async (repoPath, options) => {
+  try {
+    const engine = new AssessmentEngine({
+      repoPath,
+      includeRecommendations: true,
+      generateADR: false,
+      outputFormat: "json",
+      persona: options.persona
+    });
+    const spinner = import_ora.default("Analyzing repository and generating roadmap...").start();
+    const result = await engine.execute();
+    spinner.text = "Creating strategic roadmap...";
+    const roadmap = await generateRoadmap(result, options);
+    spinner.succeed("Roadmap generated!");
+    displayRoadmapSummary(roadmap);
+    if (options.output) {
+      await saveRoadmap(roadmap, options.output, options.format);
+    }
+  } catch (error) {
+    console.error(import_chalk.default.red("\u274C Roadmap generation failed:"), error);
+    process.exit(1);
+  }
+});
 process.on("uncaughtException", (error) => {
   console.error(import_chalk.default.red("\u274C Uncaught exception:"), error);
   process.exit(1);