thumbgate 0.9.9

package/scripts/sync-version.js

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Version Sync — Single Source of Truth
+ *
+ * Reads the version from package.json and propagates it to all
+ * manifests and public docs. Eliminates version drift permanently.
+ *
+ * Inspired by the "Pipeline Doctor" pattern (Optimum Partners, 2026)
+ * and OneUptime's automated version bumping approach.
+ *
+ * Usage:
+ *   node scripts/sync-version.js          # Sync all files
+ *   node scripts/sync-version.js --check  # Dry-run: report drift without fixing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.join(__dirname, '..');
+
+function readJson(relPath) {
+  return JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, relPath), 'utf-8'));
+}
+
+function writeJson(relPath, data) {
+  fs.writeFileSync(path.join(PROJECT_ROOT, relPath), JSON.stringify(data, null, 2) + '\n');
+}
+
+function replaceInFile(relPath, search, replace) {
+  const filePath = path.join(PROJECT_ROOT, relPath);
+  if (!fs.existsSync(filePath)) return false;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  if (!content.includes(search)) return false;
+  fs.writeFileSync(filePath, content.split(search).join(replace));
+  return true;
+}
+
+function syncJsonField(target, field, expectedValue, drifted, checkOnly) {
+  if (field !== 'version' && field !== 'homepage' && field !== 'repository') return false;
+  if (target[field] === expectedValue) return false;
+  drifted.push({ file: target.__file, field, current: target[field] });
+  if (!checkOnly) target[field] = expectedValue;
+  return true;
+}
+
+function syncVersion(opts) {
+  const options = opts || {};
+  const checkOnly = options.check || false;
+  const pkg = readJson('package.json');
+  const version = pkg.version;
+  const homepageUrl = pkg.homepage;
+  const repositoryUrl = pkg.repository && pkg.repository.url ? String(pkg.repository.url).replace(/\.git$/, '') : '';
+
+  const targets = [];
+  const drifted = [];
+
+  // 1. package-lock.json — top-level version metadata
+  const packageLockPath = 'package-lock.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, packageLockPath))) {
+    const packageLock = readJson(packageLockPath);
+    if (packageLock.version !== version) {
+      drifted.push({ file: packageLockPath, field: 'version', current: packageLock.version });
+      if (!checkOnly) {
+        packageLock.version = version;
+      }
+    }
+    if (packageLock.packages && packageLock.packages[''] && packageLock.packages[''].version !== version) {
+      drifted.push({ file: packageLockPath, field: 'packages[""].version', current: packageLock.packages[''].version });
+      if (!checkOnly) {
+        packageLock.packages[''].version = version;
+      }
+    }
+    if (!checkOnly && drifted.some((entry) => entry.file === packageLockPath)) {
+      writeJson(packageLockPath, packageLock);
+    }
+    targets.push(packageLockPath);
+  }
+
+  // 2. server.json — top-level version + packages[0].version
+  const serverJson = readJson('server.json');
+  if (serverJson.version !== version) {
+    drifted.push({ file: 'server.json', field: 'version', current: serverJson.version });
+    if (!checkOnly) {
+      serverJson.version = version;
+      if (serverJson.packages && serverJson.packages[0]) {
+        serverJson.packages[0].version = version;
+      }
+      writeJson('server.json', serverJson);
+    }
+  } else if (serverJson.packages && serverJson.packages[0] && serverJson.packages[0].version !== version) {
+    drifted.push({ file: 'server.json', field: 'packages[0].version', current: serverJson.packages[0].version });
+    if (!checkOnly) {
+      serverJson.packages[0].version = version;
+      writeJson('server.json', serverJson);
+    }
+  }
+  targets.push('server.json');
+
+  // 3. .well-known/mcp/server-card.json
+  const cardPath = '.well-known/mcp/server-card.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, cardPath))) {
+    const card = readJson(cardPath);
+    if (card.version !== version) {
+      drifted.push({ file: cardPath, field: 'version', current: card.version });
+      if (!checkOnly) {
+        card.version = version;
+        writeJson(cardPath, card);
+      }
+    }
+    targets.push(cardPath);
+  }
+
+  // 4. .claude-plugin/plugin.json
+  const claudePluginPath = '.claude-plugin/plugin.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, claudePluginPath))) {
+    const claudePlugin = readJson(claudePluginPath);
+    claudePlugin.__file = claudePluginPath;
+    const changed = [
+      syncJsonField(claudePlugin, 'version', version, drifted, checkOnly),
+      syncJsonField(claudePlugin, 'homepage', homepageUrl, drifted, checkOnly),
+      syncJsonField(claudePlugin, 'repository', repositoryUrl, drifted, checkOnly),
+    ].some(Boolean);
+    delete claudePlugin.__file;
+    if (!checkOnly && changed) {
+      writeJson(claudePluginPath, claudePlugin);
+    }
+    targets.push(claudePluginPath);
+  }
+
+  // 5. .claude-plugin/marketplace.json
+  const claudeMarketplacePath = '.claude-plugin/marketplace.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, claudeMarketplacePath))) {
+    const claudeMarketplace = readJson(claudeMarketplacePath);
+    let changed = false;
+    if (claudeMarketplace.version !== version) {
+      drifted.push({ file: claudeMarketplacePath, field: 'version', current: claudeMarketplace.version });
+      if (!checkOnly) {
+        claudeMarketplace.version = version;
+        changed = true;
+      }
+    } 
+    const currentHomepage = claudeMarketplace.plugins && claudeMarketplace.plugins[0] && claudeMarketplace.plugins[0].metadata
+      ? claudeMarketplace.plugins[0].metadata.homepage
+      : undefined;
+    if (currentHomepage !== homepageUrl) {
+      drifted.push({ file: claudeMarketplacePath, field: 'plugins[0].metadata.homepage', current: currentHomepage });
+      if (!checkOnly && claudeMarketplace.plugins && claudeMarketplace.plugins[0]) {
+        claudeMarketplace.plugins[0].metadata = claudeMarketplace.plugins[0].metadata || {};
+        claudeMarketplace.plugins[0].metadata.homepage = homepageUrl;
+        changed = true;
+      }
+    }
+    if (!checkOnly && changed) {
+      writeJson(claudeMarketplacePath, claudeMarketplace);
+    }
+    targets.push(claudeMarketplacePath);
+  }
+
+  // 6. root Cursor marketplace manifest
+  const cursorMarketplacePath = '.cursor-plugin/marketplace.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, cursorMarketplacePath))) {
+    const cursorMarketplace = readJson(cursorMarketplacePath);
+    const current = cursorMarketplace.metadata && cursorMarketplace.metadata.version;
+    if (current !== version) {
+      drifted.push({ file: cursorMarketplacePath, field: 'metadata.version', current });
+      if (!checkOnly) {
+        cursorMarketplace.metadata = cursorMarketplace.metadata || {};
+        cursorMarketplace.metadata.version = version;
+        writeJson(cursorMarketplacePath, cursorMarketplace);
+      }
+    }
+    targets.push(cursorMarketplacePath);
+  }
+
+  // 7. plugin Cursor manifest
+  const cursorPluginManifestPath = 'plugins/cursor-marketplace/.cursor-plugin/plugin.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, cursorPluginManifestPath))) {
+    const cursorPlugin = readJson(cursorPluginManifestPath);
+    cursorPlugin.__file = cursorPluginManifestPath;
+    const changed = [
+      syncJsonField(cursorPlugin, 'version', version, drifted, checkOnly),
+      syncJsonField(cursorPlugin, 'homepage', homepageUrl, drifted, checkOnly),
+      syncJsonField(cursorPlugin, 'repository', repositoryUrl, drifted, checkOnly),
+    ].some(Boolean);
+    delete cursorPlugin.__file;
+    if (!checkOnly && changed) {
+      writeJson(cursorPluginManifestPath, cursorPlugin);
+    }
+    targets.push(cursorPluginManifestPath);
+  }
+
+  // 8. Codex plugin manifest + MCP config
+  const codexPluginManifestPath = 'plugins/codex-profile/.codex-plugin/plugin.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, codexPluginManifestPath))) {
+    const codexPlugin = readJson(codexPluginManifestPath);
+    codexPlugin.__file = codexPluginManifestPath;
+    const changed = [
+      syncJsonField(codexPlugin, 'version', version, drifted, checkOnly),
+      syncJsonField(codexPlugin, 'homepage', homepageUrl, drifted, checkOnly),
+      syncJsonField(codexPlugin, 'repository', repositoryUrl, drifted, checkOnly),
+    ].some(Boolean);
+    delete codexPlugin.__file;
+    if (!checkOnly && changed) {
+      writeJson(codexPluginManifestPath, codexPlugin);
+    }
+    targets.push(codexPluginManifestPath);
+  }
+
+  const codexPluginConfigPath = 'plugins/codex-profile/.mcp.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, codexPluginConfigPath))) {
+    const codexPluginConfig = readJson(codexPluginConfigPath);
+    const server = codexPluginConfig.mcpServers && codexPluginConfig.mcpServers.rlhf;
+    const expectedArgs = ['-y', `thumbgate@${version}`, 'serve'];
+    const currentArgs = server && Array.isArray(server.args) ? server.args : [];
+    if (server && server.command === 'npx' && JSON.stringify(currentArgs) !== JSON.stringify(expectedArgs)) {
+      drifted.push({ file: codexPluginConfigPath, field: 'mcpServers.rlhf.args', current: JSON.stringify(currentArgs) });
+      if (!checkOnly) {
+        server.args = expectedArgs.slice();
+        writeJson(codexPluginConfigPath, codexPluginConfig);
+      }
+    }
+    targets.push(codexPluginConfigPath);
+  }
+
+  const claudeCodexBridgeManifestPath = 'plugins/claude-codex-bridge/.claude-plugin/plugin.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, claudeCodexBridgeManifestPath))) {
+    const bridgePlugin = readJson(claudeCodexBridgeManifestPath);
+    bridgePlugin.__file = claudeCodexBridgeManifestPath;
+    const changed = [
+      syncJsonField(bridgePlugin, 'version', version, drifted, checkOnly),
+      syncJsonField(bridgePlugin, 'homepage', homepageUrl, drifted, checkOnly),
+      syncJsonField(bridgePlugin, 'repository', repositoryUrl, drifted, checkOnly),
+    ].some(Boolean);
+    delete bridgePlugin.__file;
+    if (!checkOnly && changed) {
+      writeJson(claudeCodexBridgeManifestPath, bridgePlugin);
+    }
+    targets.push(claudeCodexBridgeManifestPath);
+  }
+
+  const claudeCodexBridgeConfigPath = 'plugins/claude-codex-bridge/.mcp.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, claudeCodexBridgeConfigPath))) {
+    const bridgeConfig = readJson(claudeCodexBridgeConfigPath);
+    const server = bridgeConfig.mcpServers && bridgeConfig.mcpServers.rlhf;
+    const expectedArgs = ['-y', `thumbgate@${version}`, 'serve'];
+    const currentArgs = server && Array.isArray(server.args) ? server.args : [];
+    if (server && server.command === 'npx' && JSON.stringify(currentArgs) !== JSON.stringify(expectedArgs)) {
+      drifted.push({ file: claudeCodexBridgeConfigPath, field: 'mcpServers.rlhf.args', current: JSON.stringify(currentArgs) });
+      if (!checkOnly) {
+        server.args = expectedArgs.slice();
+        writeJson(claudeCodexBridgeConfigPath, bridgeConfig);
+      }
+    }
+    targets.push(claudeCodexBridgeConfigPath);
+  }
+
+  // 9. plugin Cursor MCP config
+  const cursorPluginConfigPath = 'plugins/cursor-marketplace/mcp.json';
+  if (fs.existsSync(path.join(PROJECT_ROOT, cursorPluginConfigPath))) {
+    const cursorPluginConfig = readJson(cursorPluginConfigPath);
+    const server = cursorPluginConfig.mcpServers && cursorPluginConfig.mcpServers.rlhf;
+    const expectedArgs = ['-y', 'thumbgate@latest', 'serve'];
+    const currentArgs = server && Array.isArray(server.args) ? server.args : [];
+    if (server && server.command === 'npx' && JSON.stringify(currentArgs) !== JSON.stringify(expectedArgs)) {
+      drifted.push({ file: cursorPluginConfigPath, field: 'mcpServers.rlhf.args', current: JSON.stringify(currentArgs) });
+      if (!checkOnly) {
+        server.args = expectedArgs.slice();
+        writeJson(cursorPluginConfigPath, cursorPluginConfig);
+      }
+    }
+    targets.push(cursorPluginConfigPath);
+  }
+
+  // 10. docs/install files that pin the npm package version
+  const pinnedPackageTargets = [
+    'adapters/claude/.mcp.json',
+    'docs/PLUGIN_DISTRIBUTION.md',
+    'adapters/README.md',
+    'adapters/opencode/opencode.json',
+    'docs/guides/opencode-integration.md',
+    'docs/mcp-hub-submission.md',
+    'docs/VERIFICATION_EVIDENCE.md',
+    'plugins/claude-codex-bridge/README.md',
+    'plugins/claude-codex-bridge/INSTALL.md',
+    'plugins/codex-profile/README.md',
+    'plugins/codex-profile/INSTALL.md',
+    'plugins/opencode-profile/INSTALL.md',
+  ];
+  const pinnedPackagePattern = /thumbgate@\d+\.\d+\.\d+/g;
+  for (const relPath of pinnedPackageTargets) {
+    const filePath = path.join(PROJECT_ROOT, relPath);
+    if (!fs.existsSync(filePath)) continue;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const matches = content.match(pinnedPackagePattern) || [];
+    const hasDrift = matches.some((match) => match !== `thumbgate@${version}`);
+    if (hasDrift) {
+      drifted.push({ file: relPath, field: 'package-version-string', current: matches.join(', ') });
+      if (!checkOnly) {
+        fs.writeFileSync(filePath, content.replace(pinnedPackagePattern, `thumbgate@${version}`));
+      }
+    }
+    targets.push(relPath);
+  }
+
+  // 11. docs/landing-page.html — hero badge + JSON snippet
+  const landingPath = 'docs/landing-page.html';
+  if (fs.existsSync(path.join(PROJECT_ROOT, landingPath))) {
+    const landingContent = fs.readFileSync(path.join(PROJECT_ROOT, landingPath), 'utf-8');
+    // Match any version pattern in the hero badge
+    const badgeMatch = landingContent.match(/v(\d+\.\d+\.\d+) — Hosted API/);
+    if (badgeMatch && badgeMatch[1] !== version) {
+      drifted.push({ file: landingPath, field: 'hero-badge', current: badgeMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(landingPath, `v${badgeMatch[1]} — Hosted API`, `v${version} — Hosted API`);
+      }
+    }
+    // JSON snippet version
+    const jsonMatch = landingContent.match(/"version"<\/span><span class="out">: <\/span><span class="val">"(\d+\.\d+\.\d+)"/);
+    if (jsonMatch && jsonMatch[1] !== version) {
+      drifted.push({ file: landingPath, field: 'json-snippet', current: jsonMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(landingPath, `"${jsonMatch[1]}"</div>`, `"${version}"</div>`);
+      }
+    }
+    targets.push(landingPath);
+  }
+
+  // 12. docs/mcp-hub-submission.md
+  const mcpSubmPath = 'docs/mcp-hub-submission.md';
+  if (fs.existsSync(path.join(PROJECT_ROOT, mcpSubmPath))) {
+    const mcpContent = fs.readFileSync(path.join(PROJECT_ROOT, mcpSubmPath), 'utf-8');
+    const versionMatch = mcpContent.match(/## Version\s+(\d+\.\d+\.\d+)/);
+    if (versionMatch && versionMatch[1] !== version) {
+      drifted.push({ file: mcpSubmPath, field: 'version-heading', current: versionMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(mcpSubmPath, versionMatch[1], version);
+      }
+    }
+    targets.push(mcpSubmPath);
+  }
+
+  // 13. public/index.html — static landing proof pill + footer version
+  const publicIndexPath = 'public/index.html';
+  if (fs.existsSync(path.join(PROJECT_ROOT, publicIndexPath))) {
+    const publicContent = fs.readFileSync(path.join(PROJECT_ROOT, publicIndexPath), 'utf-8');
+    const heroVersionMatch = publicContent.match(/New in v(\d+\.\d+\.\d+):/);
+    if (heroVersionMatch && heroVersionMatch[1] !== version) {
+      drifted.push({ file: publicIndexPath, field: 'hero-release-note', current: heroVersionMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(publicIndexPath, `New in v${heroVersionMatch[1]}:`, `New in v${version}:`);
+      }
+    }
+
+    const proofMatch = publicContent.match(/Versioned proof: v(\d+\.\d+\.\d+)/);
+    if (proofMatch && proofMatch[1] !== version) {
+      drifted.push({ file: publicIndexPath, field: 'proof-pill', current: proofMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(publicIndexPath, `Versioned proof: v${proofMatch[1]}`, `Versioned proof: v${version}`);
+      }
+    }
+
+    const footerMatch = publicContent.match(/Context Gateway • v(\d+\.\d+\.\d+)/);
+    if (footerMatch && footerMatch[1] !== version) {
+      drifted.push({ file: publicIndexPath, field: 'footer-version', current: footerMatch[1] });
+      if (!checkOnly) {
+        replaceInFile(publicIndexPath, `Context Gateway • v${footerMatch[1]}`, `Context Gateway • v${version}`);
+      }
+    }
+    targets.push(publicIndexPath);
+  }
+
+  // 14. adapters/mcp/server-stdio.js — MCP server metadata
+  const serverStdioPath = 'adapters/mcp/server-stdio.js';
+  const serverStdioFile = path.join(PROJECT_ROOT, serverStdioPath);
+  if (fs.existsSync(serverStdioFile)) {
+    const serverStdioContent = fs.readFileSync(serverStdioFile, 'utf-8');
+    const serverInfoMatch = serverStdioContent.match(/version:\s*'(\d+\.\d+\.\d+)'/);
+    if (serverInfoMatch && serverInfoMatch[1] !== version) {
+      drifted.push({ file: serverStdioPath, field: 'server-info-version', current: serverInfoMatch[1] });
+      if (!checkOnly) {
+        fs.writeFileSync(
+          serverStdioFile,
+          serverStdioContent.replace(/version:\s*'\d+\.\d+\.\d+'/, `version: '${version}'`)
+        );
+      }
+    }
+    targets.push(serverStdioPath);
+  }
+
+  // 15. mcpize.yaml
+  const mcpizePath = 'mcpize.yaml';
+  const mcpizeFile = path.join(PROJECT_ROOT, mcpizePath);
+  if (fs.existsSync(mcpizeFile)) {
+    const mcpizeContent = fs.readFileSync(mcpizeFile, 'utf-8');
+    const mcpizeVersionRegex = /^version:\s*"[^"]+"/m;
+    const mcpizeExpected = `version: "${version}"`;
+    if (!mcpizeContent.includes(mcpizeExpected)) {
+      drifted.push({ file: mcpizePath, field: 'version', current: mcpizeContent.match(/version:\s*"([^"]+)"/)?.[1] || 'unknown' });
+      if (!checkOnly) {
+        fs.writeFileSync(mcpizeFile, mcpizeContent.replace(mcpizeVersionRegex, mcpizeExpected));
+      }
+    }
+    targets.push(mcpizePath);
+  }
+
+  return {
+    version,
+    targets,
+    drifted,
+    synced: !checkOnly && drifted.length > 0,
+    allInSync: drifted.length === 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const checkOnly = process.argv.includes('--check');
+  const result = syncVersion({ check: checkOnly });
+
+  if (result.allInSync) {
+    console.log(`✔ All ${result.targets.length} targets in sync at v${result.version}`);
+    process.exit(0);
+  }
+
+  if (checkOnly) {
+    console.error(`✖ Version drift detected (package.json = ${result.version}):`);
+    result.drifted.forEach((d) => {
+      console.error(`  ${d.file} [${d.field}] = ${d.current}`);
+    });
+    process.exit(1);
+  }
+
+  console.log(`✔ Synced ${result.drifted.length} targets to v${result.version}:`);
+  result.drifted.forEach((d) => {
+    console.log(`  ${d.file} [${d.field}]: ${d.current} → ${result.version}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { syncVersion };

package/scripts/synthetic-dpo.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Synthetic DPO Pair Augmentation — expands real feedback into larger training datasets.
+ *
+ * Takes existing DPO pairs (from export-dpo-pairs.js) and generates synthetic
+ * variations to increase dataset size for fine-tuning:
+ *
+ * 1. Principle extraction: generalize specific errors into abstract rules
+ * 2. Contrastive pairing: match unpaired errors/learnings by domain similarity
+ * 3. Scenario variation: rephrase prompts for the same chosen/rejected pair
+ *
+ * Inspired by Chroma Context-1's scalable synthetic task generation.
+ * Pro-only feature — gated via requirePro('dpo-synthesis').
+ *
+ * @module synthetic-dpo
+ */
+
+const { requirePro } = require('./pro-features');
+const { extractDomainKeys, domainOverlap, inferPrompt, buildRubricDelta } = require('./export-dpo-pairs');
+
+/**
+ * Extract an abstract principle from an error+learning pair.
+ * Turns "never run DROP on production tables" into a generalized rule.
+ */
+function extractPrinciple(pair) {
+  const rejected = pair.rejected || '';
+  const chosen = pair.chosen || '';
+  const matchedKeys = pair.metadata?.matchedKeys || [];
+
+  // Build principle from the domain keys and the contrast
+  const domain = matchedKeys.length > 0
+    ? matchedKeys.join(', ')
+    : 'general';
+
+  // Extract the "don't do X, do Y instead" pattern
+  const dontDo = rejected.length > 120
+    ? rejected.slice(0, 120).trim() + '...'
+    : rejected;
+  const doInstead = chosen.length > 120
+    ? chosen.slice(0, 120).trim() + '...'
+    : chosen;
+
+  return {
+    domain,
+    anti_pattern: dontDo,
+    correct_pattern: doInstead,
+    principle: `In ${domain} tasks: avoid "${truncate(dontDo, 60)}" — instead "${truncate(doInstead, 60)}"`,
+  };
+}
+
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + '...';
+}
+
+/**
+ * Generate scenario variations for a DPO pair by rephrasing the prompt.
+ * Creates 1-2 synthetic pairs with different prompt framings.
+ */
+function generateScenarioVariations(pair) {
+  const variations = [];
+  const matchedKeys = pair.metadata?.matchedKeys || [];
+  const domain = matchedKeys.join(', ') || 'this domain';
+
+  // Variation 1: "What should be avoided?" framing
+  variations.push({
+    prompt: `In ${domain}: what is the wrong approach and what should be done instead?`,
+    chosen: pair.chosen,
+    rejected: pair.rejected,
+    metadata: {
+      ...pair.metadata,
+      synthetic: true,
+      syntheticType: 'scenario_variation',
+      syntheticVariant: 'avoidance_framing',
+      sourceId: pair.metadata?.errorId,
+    },
+  });
+
+  // Variation 2: "Best practice" framing (only if we have enough context)
+  if (matchedKeys.length > 0) {
+    variations.push({
+      prompt: `What is the best practice for ${domain}? Compare the correct approach with a common mistake.`,
+      chosen: pair.chosen,
+      rejected: pair.rejected,
+      metadata: {
+        ...pair.metadata,
+        synthetic: true,
+        syntheticType: 'scenario_variation',
+        syntheticVariant: 'best_practice_framing',
+        sourceId: pair.metadata?.errorId,
+      },
+    });
+  }
+
+  return variations;
+}
+
+/**
+ * Build contrastive pairs from unpaired errors and learnings.
+ * Uses softer domain matching (single key overlap) to find weak matches
+ * that wouldn't qualify for primary pairing but are useful for training.
+ */
+function buildContrastivePairs(unpairedErrors, unpairedLearnings) {
+  const pairs = [];
+  const usedErrors = new Set();
+  const usedLearnings = new Set();
+
+  const errorKeys = unpairedErrors.map((e) => ({ memory: e, keys: extractDomainKeys(e) }));
+  const learningKeys = unpairedLearnings.map((l) => ({ memory: l, keys: extractDomainKeys(l) }));
+
+  // Relaxed matching: 1+ key overlap (primary pairing requires higher scores)
+  for (const err of errorKeys) {
+    if (usedErrors.has(err.memory.id)) continue;
+
+    let best = null;
+    let bestOverlap = 0;
+
+    for (const learn of learningKeys) {
+      if (usedLearnings.has(learn.memory.id)) continue;
+      const overlap = domainOverlap(err.keys, learn.keys);
+      if (overlap > bestOverlap) {
+        best = learn;
+        bestOverlap = overlap;
+      }
+    }
+
+    if (best && bestOverlap >= 1) {
+      const rubric = buildRubricDelta(err.memory, best.memory);
+      pairs.push({
+        prompt: inferPrompt(err.memory, best.memory),
+        chosen: best.memory.content,
+        rejected: err.memory.content,
+        metadata: {
+          errorId: err.memory.id,
+          learningId: best.memory.id,
+          matchScore: bestOverlap,
+          overlapScore: bestOverlap,
+          matchedKeys: err.keys.filter((k) => best.keys.includes(k)),
+          errorTitle: err.memory.title,
+          learningTitle: best.memory.title,
+          rubric,
+          synthetic: true,
+          syntheticType: 'contrastive_pair',
+        },
+      });
+      usedErrors.add(err.memory.id);
+      usedLearnings.add(best.memory.id);
+    }
+  }
+
+  return pairs;
+}
+
+/**
+ * Augment an existing DPO export with synthetic pairs.
+ *
+ * @param {object} dpoExport - Output from exportDpoFromMemories()
+ * @param {object} [options]
+ * @param {boolean} [options.scenarioVariations=true] - Generate prompt variations
+ * @param {boolean} [options.contrastivePairing=true] - Pair unmatched errors/learnings
+ * @param {boolean} [options.principleExtraction=true] - Extract abstract principles
+ * @param {boolean} [options.skipProCheck=false] - Skip Pro check (for testing)
+ * @param {Function} [options.requireProFn=requirePro] - Injectable Pro gate helper for testing
+ * @returns {{ originalPairs: number, syntheticPairs: number, totalPairs: number, pairs: object[], principles: object[] }}
+ */
+function augmentDpoExport(dpoExport, options = {}) {
+  const {
+    scenarioVariations = true,
+    contrastivePairing = true,
+    principleExtraction = true,
+    skipProCheck = false,
+    requireProFn = requirePro,
+  } = options;
+
+  // Pro gate (unless testing)
+  if (!skipProCheck && !requireProFn('dpo-synthesis')) {
+    return {
+      originalPairs: dpoExport.pairs?.length || 0,
+      syntheticPairs: 0,
+      totalPairs: dpoExport.pairs?.length || 0,
+      pairs: dpoExport.pairs || [],
+      principles: [],
+      proRequired: true,
+    };
+  }
+
+  const originalPairs = dpoExport.pairs || [];
+  const syntheticPairs = [];
+  const principles = [];
+
+  // 1. Scenario variations from existing pairs
+  if (scenarioVariations) {
+    for (const pair of originalPairs) {
+      const variations = generateScenarioVariations(pair);
+      syntheticPairs.push(...variations);
+    }
+  }
+
+  // 2. Contrastive pairing from unpaired errors/learnings
+  if (contrastivePairing) {
+    const contrastive = buildContrastivePairs(
+      dpoExport.unpairedErrors || [],
+      dpoExport.unpairedLearnings || [],
+    );
+    syntheticPairs.push(...contrastive);
+  }
+
+  // 3. Principle extraction
+  if (principleExtraction) {
+    for (const pair of originalPairs) {
+      principles.push(extractPrinciple(pair));
+    }
+  }
+
+  const allPairs = [...originalPairs, ...syntheticPairs];
+
+  return {
+    originalPairs: originalPairs.length,
+    syntheticPairs: syntheticPairs.length,
+    totalPairs: allPairs.length,
+    pairs: allPairs,
+    principles,
+  };
+}
+
+module.exports = {
+  augmentDpoExport,
+  extractPrinciple,
+  generateScenarioVariations,
+  buildContrastivePairs,
+  truncate,
+};