@nerviq/cli 0.0.1 → 0.9.0-beta.2

package/src/synergy/learning.js

@@ -0,0 +1,184 @@
+/**
+ * S1. Cross-Platform Learning Engine
+ *
+ * When a recommendation succeeds on one platform, propagate to others.
+ * Translates recommendations into each platform's native semantics
+ * rather than blindly copying.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PLATFORM_SEMANTICS = {
+  claude: { configFile: 'CLAUDE.md', format: 'markdown', instructionStyle: 'prose' },
+  codex: { configFile: 'AGENTS.md', format: 'markdown', instructionStyle: 'directive' },
+  gemini: { configFile: 'GEMINI.md', format: 'markdown', instructionStyle: 'structured' },
+  copilot: { configFile: '.github/copilot-instructions.md', format: 'markdown', instructionStyle: 'concise' },
+  cursor: { configFile: '.cursor/rules', format: 'mdc', instructionStyle: 'rule-based' },
+};
+
+const TRANSLATION_MAP = {
+  'verification-command': {
+    claude: (rec) => `Add to CLAUDE.md: \`## Verification\` section with \`${rec.command}\``,
+    codex: (rec) => `Add to AGENTS.md verification block: \`${rec.command}\``,
+    gemini: (rec) => `Add to GEMINI.md: verification command \`${rec.command}\``,
+    copilot: (rec) => `Document in copilot-instructions.md: always run \`${rec.command}\` before completing`,
+    cursor: (rec) => `Add rule: "Always run \`${rec.command}\` before completing tasks"`,
+  },
+  'architecture-doc': {
+    claude: (rec) => `Add Mermaid architecture diagram to CLAUDE.md`,
+    codex: (rec) => `Add architecture overview to AGENTS.md`,
+    gemini: (rec) => `Add architecture context to GEMINI.md`,
+    copilot: (rec) => `Add architecture reference in copilot-instructions.md`,
+    cursor: (rec) => `Add architecture context rule in .cursor/rules`,
+  },
+  'permission-rule': {
+    claude: (rec) => `Configure in settings.json permissions: ${rec.description}`,
+    codex: (rec) => `Set sandbox policy in codex config: ${rec.description}`,
+    gemini: (rec) => `Configure Gemini sandbox settings: ${rec.description}`,
+    copilot: (rec) => `Note in instructions: ${rec.description}`,
+    cursor: (rec) => `Add safety rule: ${rec.description}`,
+  },
+  'hook': {
+    claude: (rec) => `Add hook in settings.json: ${rec.description}`,
+    codex: (rec) => `Add pre/post task check: ${rec.description}`,
+    gemini: (rec) => `Add automated check: ${rec.description}`,
+    copilot: (rec) => `Add workflow step: ${rec.description}`,
+    cursor: (rec) => `Add background task rule: ${rec.description}`,
+  },
+};
+
+/**
+ * Adapt a recommendation from one platform's semantics to another.
+ */
+function adaptRecommendation(recommendation, sourcePlatform, targetPlatform) {
+  const translator = TRANSLATION_MAP[recommendation.type];
+  if (translator && translator[targetPlatform]) {
+    return translator[targetPlatform](recommendation);
+  }
+  // Generic fallback: describe the recommendation in platform-neutral terms
+  const semantics = PLATFORM_SEMANTICS[targetPlatform];
+  if (!semantics) return recommendation.description || recommendation.recommendation;
+  return `[${semantics.configFile}] ${recommendation.description || recommendation.recommendation}`;
+}
+
+/**
+ * Calculate confidence for a propagated insight based on similarity
+ * between source and target platforms.
+ */
+function calculatePropagationConfidence(insight, sourcePlatform, targetPlatform) {
+  // Base confidence from the original outcome
+  let confidence = Math.min(1, Math.max(0, (insight.score_delta || 0) / 20));
+
+  // Same instruction style = higher confidence
+  const sourceStyle = (PLATFORM_SEMANTICS[sourcePlatform] || {}).instructionStyle;
+  const targetStyle = (PLATFORM_SEMANTICS[targetPlatform] || {}).instructionStyle;
+  if (sourceStyle === targetStyle) confidence *= 1.2;
+
+  // Same format = slightly higher confidence
+  const sourceFormat = (PLATFORM_SEMANTICS[sourcePlatform] || {}).format;
+  const targetFormat = (PLATFORM_SEMANTICS[targetPlatform] || {}).format;
+  if (sourceFormat === targetFormat) confidence *= 1.1;
+
+  return Math.min(1, Math.round(confidence * 100) / 100);
+}
+
+/**
+ * Propagate an insight from one platform to others.
+ *
+ * @param {Object} insight - { type, recommendation, outcome, score_delta }
+ * @param {string} sourcePlatform - Platform where the insight originated
+ * @param {string[]} targetPlatforms - Platforms to propagate to
+ * @returns {Object[]} Adapted recommendations per target platform
+ */
+function propagateInsight(insight, sourcePlatform, targetPlatforms) {
+  return targetPlatforms
+    .filter(p => p !== sourcePlatform)
+    .map(platform => ({
+      platform,
+      adaptedRecommendation: adaptRecommendation(insight, sourcePlatform, platform),
+      confidence: calculatePropagationConfidence(insight, sourcePlatform, platform),
+      sourceEvidence: {
+        platform: sourcePlatform,
+        outcome: insight.outcome,
+        score_delta: insight.score_delta,
+      },
+    }));
+}
+
+/**
+ * Read recommendation outcomes from all platforms and find cross-learning opportunities.
+ *
+ * @param {string} dir - Project directory
+ * @returns {Object[]} Cross-learning opportunities
+ */
+function getCrossLearnings(dir) {
+  const learningsFile = path.join(dir, '.claude', 'synergy-learnings.json');
+  let learnings = [];
+  try {
+    learnings = JSON.parse(fs.readFileSync(learningsFile, 'utf8'));
+  } catch {
+    // No learnings file yet
+  }
+
+  // Group by recommendation type
+  const byType = {};
+  for (const learning of learnings) {
+    if (!byType[learning.type]) byType[learning.type] = [];
+    byType[learning.type].push(learning);
+  }
+
+  const opportunities = [];
+  for (const [type, items] of Object.entries(byType)) {
+    // Find successful outcomes
+    const successes = items.filter(i => i.outcome === 'applied' || i.outcome === 'helpful');
+    if (successes.length === 0) continue;
+
+    // Find platforms that haven't tried this yet
+    const triedPlatforms = new Set(items.map(i => i.platform));
+    const allPlatforms = Object.keys(PLATFORM_SEMANTICS);
+    const untried = allPlatforms.filter(p => !triedPlatforms.has(p));
+
+    if (untried.length > 0) {
+      const bestSuccess = successes.reduce((a, b) =>
+        (b.score_delta || 0) > (a.score_delta || 0) ? b : a
+      );
+      opportunities.push({
+        type,
+        successfulOn: successes.map(s => s.platform),
+        untestedOn: untried,
+        bestEvidence: bestSuccess,
+        propagations: propagateInsight(bestSuccess, bestSuccess.platform, untried),
+      });
+    }
+  }
+
+  return opportunities;
+}
+
+/**
+ * Record a learning outcome for later cross-platform propagation.
+ *
+ * @param {string} dir - Project directory
+ * @param {Object} outcome - { platform, type, recommendation, outcome, score_delta }
+ */
+function recordLearningOutcome(dir, outcome) {
+  const learningsFile = path.join(dir, '.claude', 'synergy-learnings.json');
+  let learnings = [];
+  try {
+    learnings = JSON.parse(fs.readFileSync(learningsFile, 'utf8'));
+  } catch {
+    // Start fresh
+  }
+
+  learnings.push({
+    ...outcome,
+    timestamp: new Date().toISOString(),
+  });
+
+  const claudeDir = path.join(dir, '.claude');
+  if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(learningsFile, JSON.stringify(learnings, null, 2));
+}
+
+module.exports = { propagateInsight, getCrossLearnings, recordLearningOutcome };

package/src/synergy/patterns.js

@@ -0,0 +1,227 @@
+/**
+ * S5. Cross-Platform Pattern Discovery
+ *
+ * Finds patterns only visible from a cross-platform perspective:
+ * recurring failures, platform-specific successes, sequence effects,
+ * and diminishing returns.
+ */
+
+const { PLATFORM_CAPABILITIES } = require('./routing');
+
+/**
+ * Detect recurring failures across platforms (root cause is project, not platform).
+ */
+function detectRecurringFailures(harmonyHistory) {
+  const patterns = [];
+  const failureCounts = {};
+
+  for (const entry of harmonyHistory) {
+    if (!entry.findings) continue;
+    for (const finding of entry.findings) {
+      if (finding.passed === false) {
+        const key = finding.key || finding.name;
+        if (!failureCounts[key]) {
+          failureCounts[key] = { key, name: finding.name, category: finding.category, platforms: new Set() };
+        }
+        failureCounts[key].platforms.add(entry.platform);
+      }
+    }
+  }
+
+  for (const [key, data] of Object.entries(failureCounts)) {
+    if (data.platforms.size >= 3) {
+      patterns.push({
+        type: 'recurring-failure',
+        description: `"${data.name || key}" fails on ${data.platforms.size} platforms — root cause is project-level, not platform-specific`,
+        key: data.key,
+        affectedPlatforms: [...data.platforms],
+        severity: data.platforms.size >= 4 ? 'high' : 'medium',
+      });
+    }
+  }
+
+  return patterns;
+}
+
+/**
+ * Detect platform-specific successes (recommendation only works on one platform).
+ */
+function detectPlatformSpecificSuccess(harmonyHistory) {
+  const patterns = [];
+  const outcomesByKey = {};
+
+  for (const entry of harmonyHistory) {
+    if (!entry.findings) continue;
+    for (const finding of entry.findings) {
+      const key = finding.key || finding.name;
+      if (!outcomesByKey[key]) outcomesByKey[key] = {};
+      outcomesByKey[key][entry.platform] = finding.passed;
+    }
+  }
+
+  for (const [key, platforms] of Object.entries(outcomesByKey)) {
+    const entries = Object.entries(platforms);
+    if (entries.length < 2) continue;
+
+    const passed = entries.filter(([, v]) => v === true);
+    const failed = entries.filter(([, v]) => v === false);
+
+    if (passed.length === 1 && failed.length >= 2) {
+      patterns.push({
+        type: 'platform-specific-success',
+        description: `"${key}" only passes on ${passed[0][0]} — fails on ${failed.map(f => f[0]).join(', ')}`,
+        key,
+        successPlatform: passed[0][0],
+        failPlatforms: failed.map(f => f[0]),
+      });
+    }
+  }
+
+  return patterns;
+}
+
+/**
+ * Analyze sequence effects (order of platform setup matters).
+ */
+function analyzeSequenceEffects(harmonyHistory) {
+  const patterns = [];
+  const sequenceScores = {};
+
+  // Group history entries by timestamp to detect sequences
+  const sorted = [...harmonyHistory].sort((a, b) =>
+    new Date(a.timestamp || 0) - new Date(b.timestamp || 0)
+  );
+
+  // Look at consecutive pairs
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const first = sorted[i];
+    const second = sorted[i + 1];
+    if (!first.platform || !second.platform || first.platform === second.platform) continue;
+
+    const seqKey = `${first.platform}→${second.platform}`;
+    if (!sequenceScores[seqKey]) {
+      sequenceScores[seqKey] = { scores: [], firstScores: [], secondScores: [] };
+    }
+
+    if (second.score !== undefined) {
+      sequenceScores[seqKey].secondScores.push(second.score);
+    }
+    if (first.score !== undefined) {
+      sequenceScores[seqKey].firstScores.push(first.score);
+    }
+  }
+
+  for (const [seq, data] of Object.entries(sequenceScores)) {
+    if (data.secondScores.length < 2) continue;
+    const avgSecond = data.secondScores.reduce((a, b) => a + b, 0) / data.secondScores.length;
+
+    // Check if reverse sequence exists and compare
+    const [first, second] = seq.split('→');
+    const reverseKey = `${second}→${first}`;
+    const reverseData = sequenceScores[reverseKey];
+
+    if (reverseData && reverseData.secondScores.length >= 2) {
+      const avgReverse = reverseData.secondScores.reduce((a, b) => a + b, 0) / reverseData.secondScores.length;
+      if (Math.abs(avgSecond - avgReverse) > 5) {
+        const better = avgSecond > avgReverse ? seq : reverseKey;
+        patterns.push({
+          type: 'sequence-effect',
+          description: `Setup order "${better}" produces better results (${Math.round(Math.max(avgSecond, avgReverse))} vs ${Math.round(Math.min(avgSecond, avgReverse))})`,
+          bestSequence: better,
+          scoreDifference: Math.round(Math.abs(avgSecond - avgReverse)),
+        });
+      }
+    }
+  }
+
+  return patterns;
+}
+
+/**
+ * Detect diminishing returns from adding more platforms.
+ */
+function detectDiminishingReturns(harmonyHistory) {
+  const patterns = [];
+
+  // Group by project (dir) and count platforms vs score improvement
+  const byProject = {};
+  for (const entry of harmonyHistory) {
+    const dir = entry.dir || 'unknown';
+    if (!byProject[dir]) byProject[dir] = [];
+    byProject[dir].push(entry);
+  }
+
+  for (const [dir, entries] of Object.entries(byProject)) {
+    const platformScores = {};
+    for (const entry of entries) {
+      if (entry.platform && entry.score !== undefined) {
+        platformScores[entry.platform] = entry.score;
+      }
+    }
+
+    const platforms = Object.keys(platformScores);
+    if (platforms.length < 3) continue;
+
+    // Sort by score descending to see marginal value of each addition
+    const sorted = Object.entries(platformScores).sort((a, b) => b[1] - a[1]);
+    const marginals = [];
+    let cumulative = 0;
+
+    for (let i = 0; i < sorted.length; i++) {
+      const marginal = i === 0 ? sorted[i][1] : Math.max(0, sorted[i][1] - cumulative / i);
+      marginals.push({ platform: sorted[i][0], score: sorted[i][1], marginalValue: Math.round(marginal) });
+      cumulative += sorted[i][1];
+    }
+
+    // Check if last platforms add significantly less
+    if (marginals.length >= 3) {
+      const firstMarginal = marginals[0].marginalValue;
+      const lastMarginal = marginals[marginals.length - 1].marginalValue;
+
+      if (firstMarginal > 0 && lastMarginal < firstMarginal * 0.3) {
+        patterns.push({
+          type: 'diminishing-returns',
+          description: `Platform #${marginals.length} (${marginals[marginals.length - 1].platform}) adds ${lastMarginal} marginal value vs ${firstMarginal} from #1 (${marginals[0].platform})`,
+          marginals,
+          dir,
+        });
+      }
+    }
+  }
+
+  return patterns;
+}
+
+/**
+ * Discover all cross-platform patterns from harmony history.
+ *
+ * @param {Object[]} harmonyHistory - Array of audit/harmony run entries
+ * @returns {Object} Discovered patterns by type
+ */
+function discoverPatterns(harmonyHistory) {
+  if (!Array.isArray(harmonyHistory) || harmonyHistory.length === 0) {
+    return { patterns: [] };
+  }
+
+  const patterns = [
+    ...detectRecurringFailures(harmonyHistory),
+    ...detectPlatformSpecificSuccess(harmonyHistory),
+    ...analyzeSequenceEffects(harmonyHistory),
+    ...detectDiminishingReturns(harmonyHistory),
+  ];
+
+  return { patterns };
+}
+
+/**
+ * Focused analysis of sequence effects only.
+ *
+ * @param {Object[]} harmonyHistory - Array of audit/harmony run entries
+ * @returns {Object[]} Sequence effect patterns
+ */
+function analyzeSequenceEffectsOnly(harmonyHistory) {
+  if (!Array.isArray(harmonyHistory)) return [];
+  return analyzeSequenceEffects(harmonyHistory);
+}
+
+module.exports = { discoverPatterns, analyzeSequenceEffects: analyzeSequenceEffectsOnly };

package/src/synergy/ranking.js

@@ -0,0 +1,83 @@
+/**
+ * S6. Unified Recommendation Ranking
+ *
+ * Ranks recommendations by cross-platform impact, boosting those that
+ * apply broadly, have evidence from other platforms, or fill gaps.
+ */
+
+/**
+ * Calculate synergy score for a single recommendation.
+ *
+ * @param {Object} recommendation - A recommendation object
+ * @param {string[]} activePlatforms - Currently active platforms
+ * @param {Object} [context] - Optional context with evidence and compensation data
+ * @returns {number} Synergy score
+ */
+function calculateSynergyScore(recommendation, activePlatforms, context) {
+  let score = recommendation.baseScore || recommendation.score || 1;
+  const ctx = context || {};
+
+  // Cross-platform boost: applies to N platforms → x1.2 per additional
+  const applicablePlatforms = (recommendation.applicablePlatforms || [])
+    .filter(p => activePlatforms.includes(p));
+  if (applicablePlatforms.length > 1) {
+    score *= Math.pow(1.2, applicablePlatforms.length - 1);
+  }
+
+  // Evidence boost: validated on another platform → x1.3
+  if (recommendation.validatedOn && recommendation.validatedOn.length > 0) {
+    const externalValidations = recommendation.validatedOn.filter(
+      p => p !== recommendation.sourcePlatform
+    );
+    if (externalValidations.length > 0) {
+      score *= 1.3;
+    }
+  }
+
+  // Compensation boost: fills a gap → x1.5
+  if (recommendation.fillsGap || recommendation.isCompensation) {
+    score *= 1.5;
+  }
+
+  // Cross-learning boost: learned from another platform → x1.2
+  if (recommendation.crossLearningSource) {
+    score *= 1.2;
+  }
+
+  // Impact multiplier
+  const impactMultipliers = { critical: 2.0, high: 1.5, medium: 1.0, low: 0.7 };
+  const impactMult = impactMultipliers[recommendation.impact] || 1.0;
+  score *= impactMult;
+
+  // Historical success boost from context
+  if (ctx.successRate !== undefined && ctx.successRate > 0) {
+    score *= (1 + ctx.successRate * 0.3);
+  }
+
+  return Math.round(score * 100) / 100;
+}
+
+/**
+ * Rank recommendations by cross-platform synergy impact.
+ *
+ * @param {Object[]} recommendations - Array of recommendation objects
+ * @param {string[]} activePlatforms - Currently active platforms
+ * @param {Object} [context] - Optional context with evidence and compensation data
+ * @returns {Object[]} Sorted recommendations with synergyScore attached
+ */
+function rankRecommendations(recommendations, activePlatforms, context) {
+  if (!Array.isArray(recommendations) || recommendations.length === 0) {
+    return [];
+  }
+
+  const platforms = activePlatforms || [];
+
+  return recommendations
+    .map(rec => ({
+      ...rec,
+      synergyScore: calculateSynergyScore(rec, platforms, context),
+    }))
+    .sort((a, b) => b.synergyScore - a.synergyScore);
+}
+
+module.exports = { rankRecommendations, calculateSynergyScore };

package/src/synergy/report.js

@@ -0,0 +1,163 @@
+/**
+ * S7. Synergy Dashboard / Report
+ *
+ * Formats synergy analysis as CLI output showing amplification,
+ * per-platform contribution, active and untapped synergies, and trends.
+ */
+
+const { compoundAudit, calculateAmplification } = require('./evidence');
+const { analyzeCompensation } = require('./compensation');
+const { discoverPatterns } = require('./patterns');
+const { rankRecommendations } = require('./ranking');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m',
+  magenta: '\x1b[35m',
+  white: '\x1b[37m',
+};
+
+function c(text, color) {
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+function progressBar(score, max = 100, width = 20) {
+  const clamped = Math.min(max, Math.max(0, score));
+  const filled = Math.round((clamped / max) * width);
+  const empty = width - filled;
+  const color = score >= 70 ? 'green' : score >= 40 ? 'yellow' : 'red';
+  return c('\u2588'.repeat(filled), color) + c('\u2591'.repeat(empty), 'dim');
+}
+
+/**
+ * Format the synergy report for CLI output.
+ *
+ * @param {Object} options
+ * @param {Object} options.platformAudits - Audit results per platform
+ * @param {string[]} options.activePlatforms - Active platform names
+ * @param {Object[]} [options.harmonyHistory] - Historical harmony data
+ * @param {Object[]} [options.recommendations] - Aggregated recommendations
+ * @returns {string} Formatted CLI report
+ */
+function formatSynergyReport(options) {
+  const { platformAudits, activePlatforms, harmonyHistory, recommendations } = options;
+  const lines = [];
+
+  // Header
+  lines.push('');
+  lines.push(c('  ╔══════════════════════════════════════════════════╗', 'blue'));
+  lines.push(c('  ║           SYNERGY DASHBOARD                     ║', 'blue'));
+  lines.push(c('  ╚══════════════════════════════════════════════════╝', 'blue'));
+  lines.push('');
+
+  // Compound audit
+  const compound = compoundAudit(platformAudits || {});
+  const amplification = calculateAmplification(platformAudits || {});
+
+  const ampColor = compound.amplification > 10 ? 'green'
+    : compound.amplification > 0 ? 'yellow' : 'red';
+
+  lines.push(c('  Synergy Score', 'bold'));
+  lines.push(`  ${progressBar(compound.compoundScore, 150, 30)} ${c(compound.compoundScore + '/100', 'bold')}` +
+    (compound.amplification > 0
+      ? ` ${c(`(+${compound.amplification} amplification)`, ampColor)}`
+      : ''));
+  lines.push(`  Best single platform: ${compound.bestSingleScore}/100`);
+  lines.push(`  Cross-validated findings: ${compound.crossValidated.length}`);
+  lines.push(`  Total unique findings: ${compound.totalFindings}`);
+  lines.push('');
+
+  // Per-platform contribution
+  lines.push(c('  Per-Platform Contribution', 'bold'));
+  for (const platform of (activePlatforms || [])) {
+    const audit = (platformAudits || {})[platform];
+    const score = audit ? audit.score : 0;
+    const coverage = compound.coverageMap[platform] || { found: 0, unique: 0, shared: 0 };
+    lines.push(`  ${c(platform.padEnd(10), 'blue')} ${progressBar(score, 100, 15)} ${score}/100  ` +
+      `${c(`unique: ${coverage.unique}`, 'dim')}  ${c(`shared: ${coverage.shared}`, 'dim')}`);
+  }
+  lines.push('');
+
+  // Active synergies (compensations)
+  const compensation = analyzeCompensation(activePlatforms || [], platformAudits);
+  if (compensation.compensations.length > 0) {
+    lines.push(c('  Active Synergies', 'bold'));
+    const shown = compensation.compensations.slice(0, 5);
+    for (const comp of shown) {
+      lines.push(`  ${c('\u2713', 'green')} ${comp.compensatedBy.platform} covers ${comp.weakness.platform}'s weakness in ${comp.weakness.label} ` +
+        `${c(`(+${comp.netBenefit} net benefit)`, 'green')}`);
+    }
+    if (compensation.compensations.length > 5) {
+      lines.push(c(`  ... and ${compensation.compensations.length - 5} more`, 'dim'));
+    }
+    lines.push('');
+  }
+
+  // Untapped synergies
+  if (compensation.uncoveredGaps.length > 0 || compensation.recommendedAdditions.length > 0) {
+    lines.push(c('  Untapped Synergies', 'bold'));
+
+    for (const gap of compensation.uncoveredGaps.slice(0, 3)) {
+      lines.push(`  ${c('\u26A0', 'yellow')} No platform covers: ${gap.label}`);
+    }
+
+    for (const rec of compensation.recommendedAdditions.slice(0, 2)) {
+      const areas = rec.wouldCover.map(w => w.label).join(', ');
+      lines.push(`  ${c('\u2192', 'blue')} Add ${c(rec.platform, 'bold')} to cover: ${areas}`);
+    }
+    lines.push('');
+  }
+
+  // Patterns (if history available)
+  if (Array.isArray(harmonyHistory) && harmonyHistory.length > 0) {
+    const { patterns } = discoverPatterns(harmonyHistory);
+    if (patterns.length > 0) {
+      lines.push(c('  Discovered Patterns', 'bold'));
+      for (const pattern of patterns.slice(0, 4)) {
+        const icon = pattern.type === 'recurring-failure' ? c('\u2717', 'red')
+          : pattern.type === 'sequence-effect' ? c('\u2194', 'blue')
+          : pattern.type === 'diminishing-returns' ? c('\u2193', 'yellow')
+          : c('\u2022', 'dim');
+        lines.push(`  ${icon} ${pattern.description}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Top ranked recommendations
+  if (Array.isArray(recommendations) && recommendations.length > 0) {
+    const ranked = rankRecommendations(recommendations, activePlatforms || []);
+    if (ranked.length > 0) {
+      lines.push(c('  Top Synergy Recommendations', 'bold'));
+      for (const rec of ranked.slice(0, 5)) {
+        const platforms = (rec.applicablePlatforms || []).join(', ') || rec.platform || '?';
+        lines.push(`  ${c(rec.synergyScore.toFixed(1).padStart(5), 'green')} ${rec.name || rec.description || rec.key} ${c(`[${platforms}]`, 'dim')}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Verdict
+  lines.push(c(`  Verdict: ${amplification.verdict.replace(/-/g, ' ')}`, 'bold'));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a full synergy report for a project directory.
+ * High-level entry point that runs compound audit + compensation + patterns.
+ *
+ * @param {Object} options - Same as formatSynergyReport options
+ * @returns {string} Formatted CLI report string
+ */
+function generateSynergyReport(options) {
+  return formatSynergyReport(options);
+}
+
+module.exports = { generateSynergyReport, formatSynergyReport };