@nerviq/cli 0.0.1 → 0.9.0-beta.2

package/src/badge.js

@@ -0,0 +1,13 @@
+function getBadgeUrl(score) {
+  const color = score >= 80 ? 'brightgreen' : score >= 60 ? 'yellow' : score >= 40 ? 'orange' : 'red';
+  const label = encodeURIComponent('Claude Code Ready');
+  const message = encodeURIComponent(`${score}/100`);
+  return `https://img.shields.io/badge/${label}-${message}-${color}`;
+}
+
+function getBadgeMarkdown(score) {
+  const url = getBadgeUrl(score);
+  return `[![Claude Code Ready](${url})](https://github.com/nerviq/nerviq)`;
+}
+
+module.exports = { getBadgeUrl, getBadgeMarkdown };

package/src/benchmark.js

@@ -0,0 +1,339 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { version } = require('../package.json');
+const { audit } = require('./audit');
+const { setup } = require('./setup');
+const { analyzeProject } = require('./analyze');
+const { getGovernanceSummary } = require('./governance');
+
+function copyProject(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '__pycache__') {
+      continue;
+    }
+    const from = path.join(sourceDir, entry.name);
+    const to = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyProject(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    } else if (entry.isSymbolicLink && entry.isSymbolicLink()) {
+      // Symlinks are skipped in benchmark sandbox — log for awareness
+      process.stderr.write(`  Note: symlink skipped in benchmark: ${entry.name}\n`);
+    }
+  }
+}
+
+function summarizeAudit(result) {
+  return {
+    score: result.score,
+    organicScore: result.organicScore,
+    passed: result.passed,
+    failed: result.failed,
+    checkCount: result.checkCount,
+    quickWins: result.quickWins,
+  };
+}
+
+function buildWorkflowEvidence(before, after, analysisReport, governanceSummary) {
+  const tasks = [
+    {
+      key: 'discover-without-writes',
+      label: 'Discover next actions without writing files',
+      passed: before.checkCount > 0 && Array.isArray(before.quickWins),
+      evidence: `Baseline audit returned ${before.checkCount} applicable checks and ${before.quickWins.length} quick wins.`,
+    },
+    {
+      key: 'starter-safe-improvement',
+      label: 'Apply starter-safe improvements in isolation',
+      passed: after.score >= before.score && after.failed <= before.failed,
+      evidence: `Score moved ${before.score} -> ${after.score}; failed checks moved ${before.failed} -> ${after.failed}.`,
+    },
+    {
+      key: 'governed-rollout-surface',
+      label: 'Expose governed rollout controls',
+      passed: governanceSummary.permissionProfiles.length >= 3 && governanceSummary.hookRegistry.length >= 1,
+      evidence: `${governanceSummary.permissionProfiles.length} profiles and ${governanceSummary.hookRegistry.length} governed hooks available.`,
+    },
+    {
+      key: 'domain-pack-guidance',
+      label: 'Recommend a domain pack for the repo',
+      passed: analysisReport.recommendedDomainPacks.length > 0,
+      evidence: analysisReport.recommendedDomainPacks.map(pack => pack.label).join(', ') || 'No domain pack recommendation generated.',
+    },
+    {
+      key: 'mcp-pack-guidance',
+      label: 'Recommend MCP packs when appropriate',
+      passed: analysisReport.recommendedMcpPacks.length > 0,
+      evidence: analysisReport.recommendedMcpPacks.map(pack => pack.label).join(', ') || 'No MCP pack recommendation generated.',
+    },
+  ];
+
+  const passed = tasks.filter(task => task.passed).length;
+  const total = tasks.length;
+  return {
+    taskPack: 'maintainer-core',
+    tasks,
+    summary: {
+      passed,
+      total,
+      coverageScore: total > 0 ? Math.round((passed / total) * 100) : 0,
+    },
+  };
+}
+
+function buildCodexWorkflowEvidence(before, after, applyResult, analysisReport, governanceSummary) {
+  const tasks = [
+    {
+      key: 'discover-without-writes',
+      label: 'Discover next actions without writing files',
+      passed: before.checkCount > 0 && Array.isArray(before.quickWins),
+      evidence: `Baseline audit returned ${before.checkCount} applicable checks and ${before.quickWins.length} quick wins.`,
+    },
+    {
+      key: 'starter-safe-improvement',
+      label: 'Apply starter-safe Codex baseline in isolation',
+      passed: after.score >= before.score && after.failed <= before.failed,
+      evidence: `Score moved ${before.score} -> ${after.score}; failed checks moved ${before.failed} -> ${after.failed}.`,
+    },
+    {
+      key: 'preserve-existing-files',
+      label: 'Preserve existing files instead of overwriting them',
+      passed: Array.isArray(applyResult.preservedFiles),
+      evidence: `${applyResult.preservedFiles ? applyResult.preservedFiles.length : 0} files were preserved instead of overwritten.`,
+    },
+    {
+      key: 'governed-rollout-surface',
+      label: 'Expose governed rollout controls',
+      passed: governanceSummary.permissionProfiles.length >= 3 && governanceSummary.hookRegistry.length >= 1,
+      evidence: `${governanceSummary.permissionProfiles.length} profiles and ${governanceSummary.hookRegistry.length} governance surfaces available.`,
+    },
+    {
+      key: 'domain-pack-guidance',
+      label: 'Recommend Codex domain packs for the repo',
+      passed: Array.isArray(analysisReport.recommendedDomainPacks) && analysisReport.recommendedDomainPacks.length > 0,
+      evidence: (analysisReport.recommendedDomainPacks || []).map((pack) => pack.label).join(', ') || 'No Codex domain pack recommendation generated.',
+    },
+    {
+      key: 'rollback-surface',
+      label: 'Emit rollback evidence for writes',
+      passed: Boolean(applyResult.rollbackArtifact),
+      evidence: applyResult.rollbackArtifact
+        ? `Rollback artifact emitted at ${applyResult.rollbackArtifact}.`
+        : 'No rollback artifact emitted.',
+    },
+  ];
+
+  const passed = tasks.filter((task) => task.passed).length;
+  const total = tasks.length;
+  return {
+    taskPack: 'codex-baseline',
+    tasks,
+    summary: {
+      passed,
+      total,
+      coverageScore: total > 0 ? Math.round((passed / total) * 100) : 0,
+    },
+  };
+}
+
+function buildExecutiveSummary(before, after, workflowEvidence) {
+  const scoreDelta = after.score - before.score;
+  const organicDelta = after.organicScore - before.organicScore;
+  const workflowCoverage = workflowEvidence.summary.coverageScore;
+  let headline = 'Benchmark did not improve the score in this run.';
+
+  if (scoreDelta < 0) {
+    headline = `Warning: score decreased by ${Math.abs(scoreDelta)} points. Setup may have introduced a regression.`;
+  } else if (scoreDelta > 0) {
+    headline = `Benchmark improved readiness by ${scoreDelta} points without touching the original repo.`;
+  } else if (before.score >= 85 && after.score >= before.score && workflowCoverage >= 80) {
+    headline = 'Benchmark confirmed the repo already meets the starter-safe baseline without regression.';
+  }
+
+  return {
+    headline,
+    scoreDelta,
+    organicDelta,
+    decisionGuidance: scoreDelta >= 20
+      ? 'Strong pilot candidate'
+      : scoreDelta >= 10
+        ? 'Promising but needs manual review'
+        : (before.score >= 85 && workflowCoverage >= 80
+          ? 'Use suggest-only mode, domain packs, or task-level benchmarks next'
+          : 'Use suggest-only mode before rollout'),
+  };
+}
+
+function buildPracticalValue(before, after, applyResult) {
+  const written = applyResult.writtenFiles || [];
+  return {
+    denyRulesAdded: written.includes('.claude/settings.json') ? 'yes' : 'no',
+    hooksCreated: written.filter(f => f.includes('hooks/')).length,
+    commandsCreated: written.filter(f => f.includes('commands/')).length,
+    agentsCreated: written.filter(f => f.includes('agents/')).length,
+    skillsCreated: written.filter(f => f.includes('skills/')).length,
+    rulesCreated: written.filter(f => f.includes('rules/')).length,
+    claudeMdCreated: written.includes('CLAUDE.md') ? 'yes' : 'no',
+    totalFilesCreated: written.length,
+    totalFilesPreserved: (applyResult.preservedFiles || []).length,
+  };
+}
+
+function buildCaseStudy(before, after, applyResult) {
+  return {
+    initialState: `Baseline score ${before.score}/100, organic ${before.organicScore}/100.`,
+    chosenMode: 'benchmark-on-isolated-copy',
+    whatChanged: applyResult.writtenFiles,
+    whatWasPreserved: applyResult.preservedFiles,
+    measuredResults: {
+      scoreDelta: after.score - before.score,
+      organicDelta: after.organicScore - before.organicScore,
+      passedDelta: after.passed - before.passed,
+    },
+    practicalValue: buildPracticalValue(before, after, applyResult),
+  };
+}
+
+function renderBenchmarkMarkdown(report) {
+  return [
+    '# Claudex Setup Benchmark Report',
+    '',
+    `- Generated by: ${report.generatedBy}`,
+    `- Created at: ${report.createdAt}`,
+    `- Source repo: ${report.directory}`,
+    '',
+    '## Methodology',
+    ...report.methodology.map(item => `- ${item}`),
+    '',
+    '## Before',
+    `- Score: ${report.before.score}/100`,
+    `- Organic score: ${report.before.organicScore}/100`,
+    `- Passing checks: ${report.before.passed}/${report.before.checkCount}`,
+    '',
+    '## After',
+    `- Score: ${report.after.score}/100`,
+    `- Organic score: ${report.after.organicScore}/100`,
+    `- Passing checks: ${report.after.passed}/${report.after.checkCount}`,
+    '',
+    '## Delta',
+    `- Score delta: ${report.delta.score}`,
+    `- Organic score delta: ${report.delta.organicScore}`,
+    `- Passed checks delta: ${report.delta.passed}`,
+    '',
+    '## Executive Summary',
+    `- ${report.executiveSummary.headline}`,
+    `- Recommendation: ${report.executiveSummary.decisionGuidance}`,
+    '',
+    '## Workflow Evidence',
+    `- Task pack: ${report.workflowEvidence.taskPack}`,
+    `- Coverage: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} (${report.workflowEvidence.summary.coverageScore}%)`,
+    ...report.workflowEvidence.tasks.map(task => `- ${task.label}: ${task.passed ? 'pass' : 'not yet'} — ${task.evidence}`),
+    '',
+    '## Case Study',
+    `- Initial state: ${report.caseStudy.initialState}`,
+    `- Chosen mode: ${report.caseStudy.chosenMode}`,
+    `- What changed: ${report.caseStudy.whatChanged.join(', ') || 'none'}`,
+    `- What was preserved: ${report.caseStudy.whatWasPreserved.join(', ') || 'none'}`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Run a before/after benchmark on an isolated copy of the project.
+ * @param {Object} options - Benchmark options.
+ * @param {string} options.dir - Project directory to benchmark.
+ * @param {string} [options.profile] - Permission profile to use during setup.
+ * @param {string[]} [options.mcpPacks] - MCP pack keys to include in setup.
+ * @returns {Promise<Object>} Benchmark report with before/after scores, delta, and workflow evidence.
+ */
+async function runBenchmark(options) {
+  const platform = options.platform || 'claude';
+  const before = await audit({ dir: options.dir, silent: true, platform });
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'claudex-benchmark-'));
+  const sandboxDir = path.join(tempRoot, 'repo');
+
+  try {
+    copyProject(options.dir, sandboxDir);
+    const applyResult = await setup({
+      dir: sandboxDir,
+      auto: true,
+      silent: true,
+      profile: options.profile,
+      mcpPacks: options.mcpPacks || [],
+      platform,
+    });
+    const after = await audit({ dir: sandboxDir, silent: true, platform });
+    const analysisReport = await analyzeProject({ dir: sandboxDir, mode: 'suggest-only', platform });
+    const governanceSummary = getGovernanceSummary(platform);
+    const workflowEvidence = platform === 'codex'
+      ? buildCodexWorkflowEvidence(before, after, applyResult, analysisReport, governanceSummary)
+      : buildWorkflowEvidence(before, after, analysisReport, governanceSummary);
+
+    return {
+      schemaVersion: 1,
+      generatedBy: `nerviq@${version}`,
+      createdAt: new Date().toISOString(),
+      directory: options.dir,
+      platform,
+      methodology: [
+        'Run a baseline audit on the source repo.',
+        'Copy the repo into a temporary isolated workspace.',
+        `Apply starter-safe ${platform === 'codex' ? 'Codex' : 'Claude'} artifacts only on the isolated copy.`,
+        'Re-run the audit and compare the results.',
+      ],
+      before: summarizeAudit(before),
+      after: summarizeAudit(after),
+      delta: {
+        score: after.score - before.score,
+        organicScore: after.organicScore - before.organicScore,
+        passed: after.passed - before.passed,
+        failed: after.failed - before.failed,
+      },
+      workflowEvidence,
+      executiveSummary: buildExecutiveSummary(before, after, workflowEvidence),
+      caseStudy: buildCaseStudy(before, after, applyResult),
+    };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function printBenchmark(report, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log('  nerviq benchmark');
+  console.log('  ═══════════════════════════════════════');
+  console.log('  Runs in an isolated temp copy. Your current repo is not modified.');
+  console.log('');
+  console.log(`  Before:  ${report.before.score}/100 (organic ${report.before.organicScore}/100)`);
+  console.log(`  After:   ${report.after.score}/100 (organic ${report.after.organicScore}/100)`);
+  console.log(`  Delta:   score ${report.delta.score >= 0 ? '+' : ''}${report.delta.score}, organic ${report.delta.organicScore >= 0 ? '+' : ''}${report.delta.organicScore}`);
+  console.log('');
+  console.log(`  ${report.executiveSummary.headline}`);
+  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
+  console.log(`  Workflow evidence: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} tasks (${report.workflowEvidence.summary.coverageScore}%)`);
+  console.log('');
+}
+
+function writeBenchmarkReport(report, outFile) {
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  const content = path.extname(outFile).toLowerCase() === '.md'
+    ? renderBenchmarkMarkdown(report)
+    : JSON.stringify(report, null, 2);
+  fs.writeFileSync(outFile, content, 'utf8');
+}
+
+module.exports = {
+  runBenchmark,
+  printBenchmark,
+  writeBenchmarkReport,
+};

package/src/claudex-sync.json

@@ -0,0 +1,7 @@
+{
+  "synced_from": "claudex",
+  "synced_at": "2026-04-02T15:12:04Z",
+  "total_items": 1107,
+  "tested": 948,
+  "last_id": 1157
+}

package/src/codex/activity.js

@@ -0,0 +1,324 @@
+/**
+ * Codex Repeat-Usage Surfaces — CP-06
+ *
+ * Adapts the shared activity/snapshot backend for Codex platform.
+ * Provides: history, compare, trend, watch, feedback, insights.
+ *
+ * Codex snapshots are stored alongside Claude snapshots in
+ * .claude/claudex-setup/snapshots/ but filtered by platform='codex'.
+ */
+
+const path = require('path');
+const {
+  getHistory: getSharedHistory,
+  compareLatest: sharedCompareLatest,
+  readSnapshotIndex,
+  writeSnapshotArtifact,
+  exportTrendReport: sharedExportTrendReport,
+  recordRecommendationOutcome,
+  readOutcomeIndex,
+  summarizeOutcomeEntries,
+} = require('../activity');
+const { version } = require('../../package.json');
+
+// --- History ---
+
+/**
+ * Get Codex audit history from snapshots.
+ * Filters to platform='codex' snapshots only.
+ */
+function getCodexHistory(dir, limit = 20) {
+  const entries = readSnapshotIndex(dir);
+  return entries
+    .filter(e => e.snapshotKind === 'audit' && (e.platform === 'codex' || e.summary?.platform === 'codex'))
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
+function formatCodexHistory(dir) {
+  const history = getCodexHistory(dir, 10);
+  if (history.length === 0) {
+    return 'No Codex snapshots found. Run `npx nerviq --platform codex --snapshot` to save one.';
+  }
+
+  const lines = ['Codex Score History (most recent first):', ''];
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || 'unknown';
+    const score = entry.summary?.score ?? '?';
+    const passed = entry.summary?.passed ?? '?';
+    const total = entry.summary?.checkCount ?? '?';
+    lines.push(`  ${date}  ${score}/100  (${passed}/${total} passing)`);
+  }
+
+  const comparison = compareCodexLatest(dir);
+  if (comparison) {
+    lines.push('');
+    const sign = comparison.delta.score >= 0 ? '+' : '';
+    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    if (comparison.improvements.length > 0) {
+      lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
+    }
+    if (comparison.regressions.length > 0) {
+      lines.push(`  New gaps: ${comparison.regressions.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// --- Compare ---
+
+/**
+ * Compare the two most recent Codex audit snapshots.
+ */
+function compareCodexLatest(dir) {
+  const audits = getCodexHistory(dir, 2);
+  if (audits.length < 2) return null;
+
+  const current = audits[0];
+  const previous = audits[1];
+
+  const delta = {
+    score: (current.summary?.score || 0) - (previous.summary?.score || 0),
+    organic: (current.summary?.organicScore || 0) - (previous.summary?.organicScore || 0),
+    passed: (current.summary?.passed || 0) - (previous.summary?.passed || 0),
+  };
+
+  const regressions = [];
+  const improvements = [];
+
+  const prevKeys = new Set(previous.summary?.topActionKeys || []);
+  const currKeys = new Set(current.summary?.topActionKeys || []);
+
+  for (const key of currKeys) {
+    if (!prevKeys.has(key)) regressions.push(key);
+  }
+  for (const key of prevKeys) {
+    if (!currKeys.has(key)) improvements.push(key);
+  }
+
+  return {
+    platform: 'codex',
+    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
+    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    delta,
+    regressions,
+    improvements,
+    trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
+  };
+}
+
+// --- Trend ---
+
+/**
+ * Export Codex trend report as markdown.
+ */
+function exportCodexTrendReport(dir) {
+  const history = getCodexHistory(dir, 50);
+  if (history.length === 0) return null;
+
+  const comparison = compareCodexLatest(dir);
+  const lines = [
+    '# Codex Setup Trend Report',
+    '',
+    `**Project:** ${path.basename(dir)}`,
+    `**Platform:** Codex`,
+    `**Generated:** ${new Date().toISOString().split('T')[0]}`,
+    `**Snapshots:** ${history.length}`,
+    '',
+    '## Score History',
+    '',
+    '| Date | Score | Passed | Checks |',
+    '|------|-------|--------|--------|',
+  ];
+
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || '?';
+    lines.push(`| ${date} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
+  }
+
+  if (comparison) {
+    lines.push('');
+    lines.push('## Latest Comparison');
+    lines.push('');
+    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
+    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Trend:** ${comparison.trend}`);
+    if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
+    if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
+  }
+
+  // ASCII trend chart
+  if (history.length >= 3) {
+    lines.push('');
+    lines.push('## Trend Chart');
+    lines.push('');
+    lines.push('```');
+    const scores = history.slice().reverse().map(e => e.summary?.score ?? 0);
+    const max = Math.max(...scores, 100);
+    const chartHeight = 10;
+    for (let row = chartHeight; row >= 0; row--) {
+      const threshold = (row / chartHeight) * max;
+      const rowLabel = String(Math.round(threshold)).padStart(3);
+      const bar = scores.map(s => s >= threshold ? '#' : ' ').join('');
+      lines.push(`${rowLabel} |${bar}`);
+    }
+    lines.push(`    +${'─'.repeat(scores.length)}`);
+    lines.push('```');
+  }
+
+  lines.push('');
+  lines.push(`---`);
+  lines.push(`*Generated by nerviq v${version} for Codex*`);
+  return lines.join('\n');
+}
+
+// --- Feedback ---
+
+/**
+ * Record feedback on a Codex recommendation.
+ */
+function recordCodexFeedback(dir, payload) {
+  return recordRecommendationOutcome(dir, {
+    ...payload,
+    source: payload.source || 'codex-cli',
+    platform: 'codex',
+  });
+}
+
+/**
+ * Get Codex feedback summary.
+ */
+function getCodexFeedbackSummary(dir) {
+  const entries = readOutcomeIndex(dir)
+    .filter(e => e.source === 'codex-cli' || e.platform === 'codex');
+  return summarizeOutcomeEntries(entries);
+}
+
+function formatCodexFeedback(dir) {
+  const summary = getCodexFeedbackSummary(dir);
+  if (!summary || Object.keys(summary).length === 0) {
+    return 'No Codex feedback recorded yet. Use `npx nerviq --platform codex feedback` to rate recommendations.';
+  }
+
+  const lines = ['Codex Recommendation Feedback:', ''];
+  const entries = Array.isArray(summary) ? summary : Object.values(summary);
+  for (const entry of entries) {
+    const key = entry.key || 'unknown';
+    const accepted = entry.accepted || 0;
+    const rejected = entry.rejected || 0;
+    const total = entry.total || 0;
+    lines.push(`  ${key}: ${accepted} accepted, ${rejected} rejected (${total} total)`);
+  }
+  return lines.join('\n');
+}
+
+// --- Insights ---
+
+/**
+ * Generate Codex-specific insights from audit history and feedback.
+ */
+function generateCodexInsights(dir) {
+  const history = getCodexHistory(dir, 50);
+  const feedback = getCodexFeedbackSummary(dir);
+  const insights = [];
+
+  // Pattern 1: Persistent failures
+  if (history.length >= 3) {
+    const recentFailKeys = new Map();
+    for (const entry of history.slice(0, 5)) {
+      for (const key of (entry.summary?.topActionKeys || [])) {
+        recentFailKeys.set(key, (recentFailKeys.get(key) || 0) + 1);
+      }
+    }
+    for (const [key, count] of recentFailKeys) {
+      if (count >= 3) {
+        insights.push({
+          type: 'persistent-failure',
+          severity: 'high',
+          key,
+          message: `Check ${key} has failed in ${count} of the last ${Math.min(history.length, 5)} audits. Consider addressing it or marking it as intentionally skipped.`,
+        });
+      }
+    }
+  }
+
+  // Pattern 2: Score regression
+  if (history.length >= 2) {
+    const scores = history.map(e => e.summary?.score ?? 0);
+    if (scores[0] < scores[1]) {
+      insights.push({
+        type: 'regression-pattern',
+        severity: 'medium',
+        message: `Score dropped from ${scores[1]} to ${scores[0]} in the most recent audit. Review recent changes.`,
+        delta: scores[0] - scores[1],
+      });
+    }
+  }
+
+  // Pattern 3: Improvement velocity stall
+  if (history.length >= 5) {
+    const recentScores = history.slice(0, 5).map(e => e.summary?.score ?? 0);
+    const range = Math.max(...recentScores) - Math.min(...recentScores);
+    if (range <= 2) {
+      insights.push({
+        type: 'velocity-stall',
+        severity: 'low',
+        message: `Score has been flat (range: ${range} points) over the last 5 audits. Consider addressing lower-priority checks.`,
+      });
+    }
+  }
+
+  // Pattern 4: Feedback signals
+  const feedbackEntries = Array.isArray(feedback) ? feedback : Object.values(feedback || {});
+  for (const entry of feedbackEntries) {
+    if (entry.rejected > entry.accepted && entry.total >= 2) {
+      insights.push({
+        type: 'feedback-signal',
+        severity: 'medium',
+        key: entry.key,
+        message: `Recommendation ${entry.key} has been rejected more than accepted (${entry.rejected}/${entry.total}). Consider adjusting or removing this recommendation.`,
+      });
+    }
+  }
+
+  return {
+    platform: 'codex',
+    generatedAt: new Date().toISOString(),
+    snapshotCount: history.length,
+    feedbackCount: feedbackEntries.length,
+    insights,
+    summary: insights.length === 0
+      ? 'No actionable insights detected. Keep running audits to build pattern data.'
+      : `${insights.length} insight(s) detected across ${history.length} snapshots.`,
+  };
+}
+
+function formatCodexInsights(dir) {
+  const result = generateCodexInsights(dir);
+  if (result.insights.length === 0) {
+    return result.summary;
+  }
+
+  const lines = ['Codex Insights:', ''];
+  for (const insight of result.insights) {
+    const severity = insight.severity.toUpperCase();
+    lines.push(`  [${severity}] ${insight.message}`);
+  }
+  lines.push('');
+  lines.push(result.summary);
+  return lines.join('\n');
+}
+
+module.exports = {
+  getCodexHistory,
+  formatCodexHistory,
+  compareCodexLatest,
+  exportCodexTrendReport,
+  recordCodexFeedback,
+  getCodexFeedbackSummary,
+  formatCodexFeedback,
+  generateCodexInsights,
+  formatCodexInsights,
+};