thumbgate 0.9.9

package/scripts/dispatch-brief.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+'use strict';
+
+const { summarizePermissionTier } = require('./agent-readiness');
+const { getOperationalDashboard } = require('./operational-dashboard');
+
+const DISPATCH_TASK_DESCRIPTIONS = {
+  recall: 'Recall prior mistakes and prevention rules before planning.',
+  feedback_summary: 'Summarize recent wins, failures, and operator notes.',
+  search_lessons: 'Search promoted lessons and inspect what corrective action the system linked to each one.',
+  retrieve_lessons: 'Retrieve top-K relevant lessons for a given tool/action context (per-action guidance).',
+  search_rlhf: 'Search raw ThumbGate feedback, ContextFS memory, and prevention rules.',
+  feedback_stats: 'Inspect approval trends and failure domains.',
+  diagnose_failure: 'Explain why a run failed or was blocked.',
+  list_intents: 'List available workflow plans without executing them.',
+  plan_intent: 'Plan a workflow with checkpoints and no execution.',
+  context_provenance: 'Audit recent context and evidence decisions.',
+  gate_stats: 'Review blocked and warned gate trends.',
+  dashboard: 'Summarize health, proof, gates, and pipeline metrics.',
+  get_business_metrics: 'Read revenue, conversion, and customer metrics.',
+  describe_semantic_entity: 'Explain Customer, Revenue, or Funnel state.',
+  enforcement_matrix: 'Full pipeline state: feedback counts, promotion rate, active gates, rejection ledger.',
+  get_reliability_rules: 'Review active prevention rules and success patterns.',
+  describe_reliability_entity: 'Alias for semantic entity definitions.',
+};
+
+const DISPATCH_BLOCKED_TASKS = [
+  'Direct code edits or git writes from the primary checkout.',
+  'Starting or completing handoffs from the remote session.',
+  'Memory writes, context-pack writes, or gate satisfaction mutations.',
+  'Admin-only billing or workflow mutation endpoints.',
+];
+
+const DISPATCH_PROMPTS = [
+  'Summarize revenue, funnel, gates, and proof-backed workflow health for the last 7d.',
+  'Explain the top blocked gate and the repeated mistake it is preventing.',
+  'Plan the next workflow-hardening sprint for this repo without executing any changes.',
+];
+
+function buildDispatchBrief(data, options = {}) {
+  const profileName = String(options.profile || 'dispatch').trim() || 'dispatch';
+  const permissions = summarizePermissionTier(profileName);
+  const analytics = data.analytics || {};
+  const revenue = analytics.revenue || {};
+  const funnel = analytics.funnel || {};
+  const northStar = analytics.northStar || {};
+  const gateStats = data.gateStats || {};
+  const readiness = data.readiness || {};
+  const operational = data.operational || {};
+
+  const allowedTasks = permissions.allowedTools
+    .map((toolName) => ({
+      tool: toolName,
+      description: DISPATCH_TASK_DESCRIPTIONS[toolName],
+    }))
+    .filter((entry) => entry.description);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    source: options.source || operational.source || 'local',
+    fallbackReason: options.fallbackReason || operational.fallbackReason || null,
+    profile: permissions.profile,
+    tier: permissions.tier,
+    writeCapable: permissions.writeCapable,
+    readiness: {
+      overallStatus: readiness.overallStatus || 'unknown',
+      runtimeMode: readiness.runtime && readiness.runtime.mode ? readiness.runtime.mode : 'unknown',
+      bootstrapReady: Boolean(readiness.bootstrap && readiness.bootstrap.ready),
+    },
+    metrics: {
+      bookedRevenueUsd: Number(((Number(revenue.bookedRevenueCents || 0)) / 100).toFixed(2)),
+      paidOrders: revenue.paidOrders || 0,
+      uniqueLeads: funnel.uniqueLeads || 0,
+      visitors: funnel.visitors || 0,
+      checkoutStarts: funnel.checkoutStarts || 0,
+      weeklyProofBackedWorkflowRuns: northStar.weeklyActiveProofBackedWorkflowRuns || 0,
+      weeklyTeamsRunningProofBackedWorkflows: northStar.weeklyTeamsRunningProofBackedWorkflows || 0,
+      activeGates: gateStats.totalGates || 0,
+      blockedActions: gateStats.blocked || 0,
+      warnedActions: gateStats.warned || 0,
+      topBlockedGate: gateStats.topBlocked
+        ? {
+          id: gateStats.topBlocked,
+          count: gateStats.topBlockedCount || 0,
+        }
+        : null,
+    },
+    allowedTasks,
+    blockedTasks: DISPATCH_BLOCKED_TASKS,
+    promptTemplates: DISPATCH_PROMPTS,
+  };
+}
+
+function formatDispatchBrief(brief) {
+  const lines = [];
+  lines.push('Dispatch Ops Brief');
+  lines.push('─'.repeat(40));
+  lines.push(`Source                : ${brief.source}${brief.fallbackReason ? ` (${brief.fallbackReason})` : ''}`);
+  lines.push(`Profile               : ${brief.profile} (${brief.tier})`);
+  lines.push(`Readiness             : ${brief.readiness.overallStatus}`);
+  lines.push(`Runtime               : ${brief.readiness.runtimeMode}`);
+  lines.push(`Bootstrap             : ${brief.readiness.bootstrapReady ? 'ready' : 'missing context'}`);
+  lines.push('');
+  lines.push('Key Metrics');
+  lines.push(`  Booked revenue      : $${brief.metrics.bookedRevenueUsd.toFixed(2)}`);
+  lines.push(`  Paid orders         : ${brief.metrics.paidOrders}`);
+  lines.push(`  Unique leads        : ${brief.metrics.uniqueLeads}`);
+  lines.push(`  Visitors            : ${brief.metrics.visitors}`);
+  lines.push(`  Checkout starts     : ${brief.metrics.checkoutStarts}`);
+  lines.push(`  Weekly proof runs   : ${brief.metrics.weeklyProofBackedWorkflowRuns}`);
+  lines.push(`  Weekly teams        : ${brief.metrics.weeklyTeamsRunningProofBackedWorkflows}`);
+  lines.push(`  Active gates        : ${brief.metrics.activeGates}`);
+  lines.push(`  Blocked actions     : ${brief.metrics.blockedActions}`);
+  lines.push(`  Warned actions      : ${brief.metrics.warnedActions}`);
+  if (brief.metrics.topBlockedGate) {
+    lines.push(`  Top blocked gate    : ${brief.metrics.topBlockedGate.id} (${brief.metrics.topBlockedGate.count}x)`);
+  }
+  lines.push('');
+  lines.push('Safe Remote Tasks');
+  brief.allowedTasks.forEach((entry) => {
+    lines.push(`- ${entry.tool}: ${entry.description}`);
+  });
+  lines.push('');
+  lines.push('Do Not Do From Dispatch');
+  brief.blockedTasks.forEach((task) => {
+    lines.push(`- ${task}`);
+  });
+  lines.push('');
+  lines.push('Prompt Templates');
+  brief.promptTemplates.forEach((prompt) => {
+    lines.push(`- ${prompt}`);
+  });
+  return `${lines.join('\n')}\n`;
+}
+
+async function getDispatchBrief(options = {}) {
+  const profile = String(options.profile || 'dispatch').trim() || 'dispatch';
+  const { source, data, fallbackReason } = await getOperationalDashboard(options);
+  return buildDispatchBrief(data, { profile, source, fallbackReason });
+}
+
+module.exports = {
+  DISPATCH_BLOCKED_TASKS,
+  DISPATCH_PROMPTS,
+  buildDispatchBrief,
+  formatDispatchBrief,
+  getDispatchBrief,
+};
+
+if (require.main === module) {
+  getDispatchBrief()
+    .then((brief) => {
+      process.stdout.write(formatDispatchBrief(brief));
+    })
+    .catch((err) => {
+      console.error(err && err.message ? err.message : err);
+      process.exit(1);
+    });
+}

package/scripts/distribution-surfaces.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+const PRODUCTHUNT_URL = 'https://www.producthunt.com/products/thumbgate';
+const CLAUDE_PLUGIN_LATEST_ASSET_NAME = 'thumbgate-claude-desktop.mcpb';
+
+function readJson(root, relativePath) {
+  return JSON.parse(fs.readFileSync(path.join(root, relativePath), 'utf8'));
+}
+
+function getPackageVersion(root = ROOT) {
+  return String(readJson(root, 'package.json').version || '').trim();
+}
+
+function getRepositoryUrl(root = ROOT) {
+  return String(readJson(root, 'package.json').repository.url || '').replace(/\.git$/, '');
+}
+
+function getClaudePluginVersionedAssetName(version = getPackageVersion(ROOT)) {
+  const normalized = String(version || '').replace(/^v/, '');
+  return `thumbgate-claude-desktop-v${normalized}.mcpb`;
+}
+
+function getClaudePluginLatestDownloadUrl(root = ROOT) {
+  return `${getRepositoryUrl(root)}/releases/latest/download/${CLAUDE_PLUGIN_LATEST_ASSET_NAME}`;
+}
+
+function getClaudePluginVersionedDownloadUrl(root = ROOT, version = getPackageVersion(root)) {
+  const normalized = String(version || '').replace(/^v/, '');
+  return `${getRepositoryUrl(root)}/releases/download/v${normalized}/${getClaudePluginVersionedAssetName(normalized)}`;
+}
+
+module.exports = {
+  CLAUDE_PLUGIN_LATEST_ASSET_NAME,
+  PRODUCTHUNT_URL,
+  getClaudePluginLatestDownloadUrl,
+  getClaudePluginVersionedAssetName,
+  getClaudePluginVersionedDownloadUrl,
+  getPackageVersion,
+  getRepositoryUrl,
+};

package/scripts/dpo-optimizer.js

@@ -0,0 +1,206 @@
+'use strict';
+/**
+ * DPO Batch Optimizer (DPO-02)
+ *
+ * Builds (chosen, rejected) preference pairs from feedback-log.jsonl memories,
+ * computes DPO log-ratio adjustments using Thompson Sampling posteriors,
+ * and writes dpo-model.json to THUMBGATE_FEEDBACK_DIR.
+ *
+ * Does NOT call any external API. Pure offline batch optimization.
+ *
+ * Exports: run, buildPreferencePairs, applyDpoAdjustments, dpoLogRatio
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getEffectiveSetting } = require('./evolution-state');
+const { resolveFeedbackDir } = require('./feedback-paths');
+
+const DPO_BETA = 0.1;
+
+// ---------------------------------------------------------------------------
+// dpoLogRatio — DPO preference adjustment formula
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute DPO adjustment in range [-1, +1] from chosen and rejected weights.
+ *
+ * @param {number} chosenWeight  - Time-decay weight for chosen (positive) outcome
+ * @param {number} rejectedWeight - Time-decay weight for rejected (negative) outcome
+ * @param {number} [beta=0.1]   - Temperature parameter (lower = more aggressive)
+ * @returns {number} Adjustment in [-1, +1]
+ */
+function dpoLogRatio(chosenWeight, rejectedWeight, beta) {
+  const b = (beta !== undefined && beta !== null) ? beta : getEffectiveSetting('dpo_beta', DPO_BETA);
+  const cw = Math.max(chosenWeight, 0.01);
+  const rw = Math.max(rejectedWeight, 0.01);
+  const logRatio = Math.log(cw) - Math.log(rw);
+  const sigmoid = 1.0 / (1.0 + Math.exp(-b * logRatio));
+  return (sigmoid - 0.5) * 2;
+}
+
+// ---------------------------------------------------------------------------
+// buildPreferencePairs — groups DPO pairs by category from feedbackDir
+// ---------------------------------------------------------------------------
+
+/**
+ * Build preference pairs grouped by category.
+ *
+ * Uses buildDpoPairs() from export-dpo-pairs.js (do NOT reimplement).
+ * Reads memory-log.jsonl from feedbackDir to get error + learning memories.
+ *
+ * @param {string} feedbackDir - Directory containing memory-log.jsonl
+ * @returns {Object} Map of category → [{ chosen, rejected }]
+ */
+function buildPreferencePairs(feedbackDir) {
+  const { buildDpoPairs, readJSONL } = require('./export-dpo-pairs');
+  const memoryLogPath = path.join(feedbackDir, 'memory-log.jsonl');
+  const memories = readJSONL(memoryLogPath);
+
+  const errors = memories.filter((m) => m.category === 'error');
+  const learnings = memories.filter((m) => m.category === 'learning');
+
+  const result = buildDpoPairs(errors, learnings);
+
+  // Group pairs by category (inferred from matchedKeys or tags)
+  const grouped = {};
+  for (const pair of result.pairs) {
+    const keys = (pair.metadata && pair.metadata.matchedKeys) || [];
+    const category = keys.length > 0 ? keys[0] : 'uncategorized';
+    if (!grouped[category]) grouped[category] = [];
+    grouped[category].push({
+      chosen: pair.metadata
+        ? { id: pair.metadata.learningId, content: pair.chosen, timestamp: null }
+        : { content: pair.chosen },
+      rejected: pair.metadata
+        ? { id: pair.metadata.errorId, content: pair.rejected, timestamp: null }
+        : { content: pair.rejected },
+      metadata: pair.metadata,
+    });
+  }
+
+  return grouped;
+}
+
+// ---------------------------------------------------------------------------
+// applyDpoAdjustments — mutates Thompson model with DPO posterior adjustments
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply DPO adjustments to Thompson Sampling posteriors and save the model.
+ *
+ * CRITICAL: calls ts.saveModel(model, modelPath) after all mutations.
+ *
+ * @param {string} modelPath - Path to feedback_model.json
+ * @param {Object} pairs     - Map of category → [{ chosen, rejected }] from buildPreferencePairs
+ * @returns {Object} adjustments - Map of category → { pairs, avg_adjustment }
+ */
+function applyDpoAdjustments(modelPath, pairs) {
+  const ts = require('./thompson-sampling');
+  const model = ts.loadModel(modelPath);
+  const adjustments = {};
+
+  for (const [cat, catPairs] of Object.entries(pairs)) {
+    if (!catPairs || catPairs.length === 0) continue;
+
+    // Ensure category exists in model
+    if (!model.categories[cat]) {
+      model.categories[cat] = { alpha: 1.0, beta: 1.0, samples: 0, last_updated: null };
+    }
+
+    let total = 0;
+    for (const pair of catPairs) {
+      const chosenTs = (pair.chosen && pair.chosen.timestamp) || null;
+      const rejectedTs = (pair.rejected && pair.rejected.timestamp) || null;
+      const cw = ts.timeDecayWeight(chosenTs);
+      const rw = ts.timeDecayWeight(rejectedTs);
+      total += dpoLogRatio(cw, rw);
+    }
+
+    const avg = total / catPairs.length;
+
+    if (avg > 0) {
+      model.categories[cat].alpha += avg * catPairs.length * 0.5;
+    } else {
+      model.categories[cat].beta += Math.abs(avg) * catPairs.length * 0.5;
+    }
+
+    adjustments[cat] = {
+      pairs: catPairs.length,
+      avg_adjustment: Math.round(avg * 10000) / 10000,
+    };
+  }
+
+  // CRITICAL: save after all mutations (Pitfall 2 from RESEARCH.md)
+  ts.saveModel(model, modelPath);
+
+  return adjustments;
+}
+
+// ---------------------------------------------------------------------------
+// run — top-level batch DPO optimization entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full DPO optimization batch:
+ * 1. Build preference pairs from memory-log.jsonl
+ * 2. Apply DPO adjustments to Thompson model
+ * 3. Write dpo-model.json to feedbackDir
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.feedbackDir] - Override THUMBGATE_FEEDBACK_DIR
+ * @param {string} [opts.modelPath]   - Override Thompson model path
+ * @returns {{ adjustments: Object, pairs_processed: number }}
+ */
+function run(opts) {
+  const options = opts || {};
+  const feedbackDir = options.feedbackDir || resolveFeedbackDir();
+  const modelPath = options.modelPath || path.join(feedbackDir, 'feedback_model.json');
+
+  const pairs = buildPreferencePairs(feedbackDir);
+
+  const pairsProcessed = Object.values(pairs).reduce((sum, arr) => sum + arr.length, 0);
+
+  let adjustments = {};
+  if (pairsProcessed > 0) {
+    adjustments = applyDpoAdjustments(modelPath, pairs);
+  }
+
+  const dpoModel = {
+    generated: new Date().toISOString(),
+    pairs_processed: pairsProcessed,
+    adjustments,
+  };
+
+  const dpoModelPath = path.join(feedbackDir, 'dpo-model.json');
+  if (!fs.existsSync(feedbackDir)) {
+    fs.mkdirSync(feedbackDir, { recursive: true });
+  }
+  fs.writeFileSync(dpoModelPath, `${JSON.stringify(dpoModel, null, 2)}\n`);
+
+  console.log(`DPO optimization complete: ${pairsProcessed} pairs processed`);
+  if (Object.keys(adjustments).length > 0) {
+    console.log('Adjustments:', JSON.stringify(adjustments, null, 2));
+  } else {
+    console.log('No adjustment pairs found (empty or no overlapping memories)');
+  }
+
+  return { adjustments, pairs_processed: pairsProcessed };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+if (require.main === module && process.argv.includes('--run')) {
+  run().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { run, buildPreferencePairs, applyDpoAdjustments, dpoLogRatio };

package/scripts/ensure-repo-bootstrap.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(process.argv[2] || process.cwd());
+const RLHF_ENTRY = {
+  command: 'npx',
+  args: ['-y', 'mcp-memory-gateway@latest', 'serve'],
+};
+const LEGACY_SERVER_NAMES = ['thumbgate', 'rlhf_feedback_loop'];
+const INFO_EXCLUDE_ENTRIES = ['.rlhf/', '.thumbgate/', '.mcp.json'];
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonIfChanged(filePath, value) {
+  const next = JSON.stringify(value, null, 2) + '\n';
+  let current = null;
+  try {
+    current = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    current = null;
+  }
+  if (current === next) {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return true;
+}
+
+function mergeRlhfEntry(entry = {}) {
+  return {
+    ...entry,
+    command: RLHF_ENTRY.command,
+    args: RLHF_ENTRY.args.slice(),
+  };
+}
+
+function ensureMcpJson(repoRoot) {
+  const filePath = path.join(repoRoot, '.mcp.json');
+  const existing = readJson(filePath);
+  const config = existing && typeof existing === 'object' ? existing : {};
+  config.mcpServers = config.mcpServers && typeof config.mcpServers === 'object' ? config.mcpServers : {};
+  config.mcpServers.rlhf = mergeRlhfEntry(config.mcpServers.rlhf);
+  for (const legacyName of LEGACY_SERVER_NAMES) {
+    delete config.mcpServers[legacyName];
+  }
+  return writeJsonIfChanged(filePath, config);
+}
+
+function ensureClaudeSettings(repoRoot) {
+  const filePath = path.join(repoRoot, '.claude', 'settings.json');
+  const existing = readJson(filePath);
+  if (!existing || typeof existing !== 'object') {
+    return false;
+  }
+  const hasRelevantServer =
+    Boolean(existing.mcpServers && existing.mcpServers.rlhf) ||
+    LEGACY_SERVER_NAMES.some((name) => Boolean(existing.mcpServers && existing.mcpServers[name]));
+  if (!hasRelevantServer) {
+    return false;
+  }
+  existing.mcpServers = existing.mcpServers && typeof existing.mcpServers === 'object' ? existing.mcpServers : {};
+  existing.mcpServers.rlhf = mergeRlhfEntry(existing.mcpServers.rlhf);
+  for (const legacyName of LEGACY_SERVER_NAMES) {
+    delete existing.mcpServers[legacyName];
+  }
+  return writeJsonIfChanged(filePath, existing);
+}
+
+function ensureInfoExclude(repoRoot) {
+  const excludePath = path.join(repoRoot, '.git', 'info', 'exclude');
+  let current = '';
+  try {
+    current = fs.readFileSync(excludePath, 'utf8');
+  } catch {
+    current = '';
+  }
+  const lines = new Set(
+    current
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+  );
+  let changed = false;
+  for (const entry of INFO_EXCLUDE_ENTRIES) {
+    if (!lines.has(entry)) {
+      lines.add(entry);
+      changed = true;
+    }
+  }
+  if (!changed) {
+    return false;
+  }
+  const next = `${Array.from(lines).sort().join('\n')}\n`;
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+  fs.writeFileSync(excludePath, next);
+  return true;
+}
+
+function ensureRlhfDir(repoRoot) {
+  const rlhfDir = path.join(repoRoot, '.rlhf');
+  if (fs.existsSync(rlhfDir)) {
+    return false;
+  }
+  fs.mkdirSync(rlhfDir, { recursive: true });
+  return true;
+}
+
+function main() {
+  const results = {
+    repoRoot: REPO_ROOT,
+    createdRlhfDir: ensureRlhfDir(REPO_ROOT),
+    updatedMcpJson: ensureMcpJson(REPO_ROOT),
+    updatedClaudeSettings: ensureClaudeSettings(REPO_ROOT),
+    updatedInfoExclude: ensureInfoExclude(REPO_ROOT),
+  };
+  process.stdout.write(`${JSON.stringify(results)}\n`);
+}
+
+main();