thumbgate 0.9.10

package/scripts/audit-trail.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Audit Trail — OpenShell-inspired governance layer
+ *
+ * Records every gate decision (allow/deny/warn) into a structured audit log,
+ * then auto-feeds deny/warn decisions into the ThumbGate feedback pipeline as
+ * negative signal. This closes the loop: gate blocks → feedback capture →
+ * prevention rule generation → stronger gates.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveFeedbackDir } = require('./feedback-paths');
+
+const AUDIT_LOG_FILENAME = 'audit-trail.jsonl';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+function getAuditLogPath() {
+  return path.join(resolveFeedbackDir(), AUDIT_LOG_FILENAME);
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core audit record
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} params
+ * @param {string} params.toolName   — tool that was evaluated
+ * @param {object} params.toolInput  — the tool input payload
+ * @param {string} params.decision   — 'allow' | 'deny' | 'warn'
+ * @param {string} [params.gateId]   — which gate matched (null for allow)
+ * @param {string} [params.message]  — gate message
+ * @param {string} [params.severity] — gate severity
+ * @param {number} [params.latencyMs] — tool execution time in milliseconds
+ * @param {string} [params.source]   — 'gates-engine' | 'secret-guard' | 'mcp-policy' | 'profile-router' | 'tool-latency'
+ * @returns {object} the stored audit record
+ */
+function recordAuditEvent(params = {}) {
+  const logPath = getAuditLogPath();
+  ensureDir(path.dirname(logPath));
+
+  const record = {
+    id: `audit_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    timestamp: new Date().toISOString(),
+    toolName: params.toolName || 'unknown',
+    toolInput: sanitizeToolInput(params.toolInput || {}),
+    decision: params.decision || 'allow',
+    gateId: params.gateId || null,
+    message: params.message || null,
+    severity: params.severity || null,
+    latencyMs: typeof params.latencyMs === 'number' ? params.latencyMs : null,
+    source: params.source || 'gates-engine',
+  };
+
+  fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+  return record;
+}
+
+/**
+ * Strip secrets and large payloads from tool input before audit storage.
+ */
+function sanitizeToolInput(toolInput) {
+  const safe = {};
+  const MAX_VALUE_LEN = 200;
+
+  for (const [key, value] of Object.entries(toolInput)) {
+    if (typeof value === 'string') {
+      // Never log content/new_string/old_string verbatim — could contain secrets
+      if (['content', 'new_string', 'old_string'].includes(key)) {
+        safe[key] = `[redacted:${value.length} chars]`;
+      } else {
+        safe[key] = value.length > MAX_VALUE_LEN
+          ? value.slice(0, MAX_VALUE_LEN) + '...'
+          : value;
+      }
+    } else {
+      safe[key] = value;
+    }
+  }
+  return safe;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-feedback from audit events
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts deny/warn audit events into ThumbGate feedback signal.
+ * This is the core OpenShell insight: policy decisions ARE training signal.
+ */
+function auditToFeedback(auditRecord) {
+  if (auditRecord.decision === 'allow') return null;
+
+  try {
+    const feedbackLoop = require('./feedback-loop');
+    const signal = auditRecord.decision === 'deny' ? 'down' : 'down';
+    const context = `Gate "${auditRecord.gateId}" ${auditRecord.decision === 'deny' ? 'blocked' : 'warned'} tool "${auditRecord.toolName}": ${auditRecord.message || 'no message'}`;
+
+    return feedbackLoop.captureFeedback({
+      signal,
+      context,
+      what_went_wrong: `Agent attempted action blocked by policy gate: ${auditRecord.gateId}`,
+      what_to_change: auditRecord.message || 'Follow safety policy before attempting this action',
+      tags: ['audit-trail', 'auto-capture', `gate:${auditRecord.gateId}`, auditRecord.source].filter(Boolean),
+      title: `MISTAKE: Policy violation — ${auditRecord.gateId}`,
+    });
+  } catch {
+    // Feedback capture failure should never break the audit trail
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read / query audit log
+// ---------------------------------------------------------------------------
+
+function readAuditLog(logPath) {
+  const p = logPath || getAuditLogPath();
+  if (!fs.existsSync(p)) return [];
+  const raw = fs.readFileSync(p, 'utf-8').trim();
+  if (!raw) return [];
+  return raw.split('\n').map(line => {
+    try { return JSON.parse(line); }
+    catch { return null; }
+  }).filter(Boolean);
+}
+
+function auditStats(logPath) {
+  const entries = readAuditLog(logPath);
+  const stats = { total: entries.length, allow: 0, deny: 0, warn: 0, byGate: {}, bySource: {} };
+
+  for (const entry of entries) {
+    stats[entry.decision] = (stats[entry.decision] || 0) + 1;
+    if (entry.gateId) {
+      if (!stats.byGate[entry.gateId]) stats.byGate[entry.gateId] = { deny: 0, warn: 0, allow: 0 };
+      stats.byGate[entry.gateId][entry.decision] = (stats.byGate[entry.gateId][entry.decision] || 0) + 1;
+    }
+    if (entry.source) {
+      stats.bySource[entry.source] = (stats.bySource[entry.source] || 0) + 1;
+    }
+  }
+
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Skill Adherence Measurement (M2.7-inspired)
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes skill adherence rate per tool from audit trail data.
+ * Adherence = allow / (allow + deny + warn) per tool.
+ * M2.7 tracks "97% skill adherence across 40+ skills" — this gives us the same metric.
+ *
+ * @param {string} [logPath]
+ * @returns {{ overall: number, byTool: Object<string, { allow: number, deny: number, warn: number, adherence: number }>, totalTools: number }}
+ */
+function skillAdherence(logPath) {
+  const entries = readAuditLog(logPath);
+  const byTool = {};
+
+  for (const entry of entries) {
+    const tool = entry.toolName || 'unknown';
+    if (!byTool[tool]) byTool[tool] = { allow: 0, deny: 0, warn: 0 };
+    byTool[tool][entry.decision] = (byTool[tool][entry.decision] || 0) + 1;
+  }
+
+  let totalAllow = 0;
+  let totalAll = 0;
+  for (const [, counts] of Object.entries(byTool)) {
+    const all = counts.allow + counts.deny + counts.warn;
+    counts.adherence = all > 0 ? Math.round((counts.allow / all) * 10000) / 100 : 100;
+    totalAllow += counts.allow;
+    totalAll += all;
+  }
+
+  return {
+    overall: totalAll > 0 ? Math.round((totalAllow / totalAll) * 10000) / 100 : 100,
+    byTool,
+    totalTools: Object.keys(byTool).length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Deny-triggered self-heal (M2.7 self-evolution loop)
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks if recent audit denials exceed a threshold, triggering autonomous self-heal.
+ * This closes the M2.7-inspired loop: audit deny → self-heal → eval → keep/revert.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.windowMs=300000] — lookback window (default 5 min)
+ * @param {number} [opts.denyThreshold=3] — denials in window to trigger heal
+ * @param {string} [opts.logPath]
+ * @returns {{ triggered: boolean, recentDenials: number, threshold: number, healResult?: object }}
+ */
+function evaluateSelfHealTrigger(opts = {}) {
+  const windowMs = opts.windowMs || 5 * 60 * 1000;
+  const denyThreshold = opts.denyThreshold || 3;
+  const entries = readAuditLog(opts.logPath);
+  const cutoff = Date.now() - windowMs;
+
+  const recentDenials = entries.filter(e =>
+    e.decision === 'deny' && new Date(e.timestamp).getTime() > cutoff
+  );
+
+  if (recentDenials.length < denyThreshold) {
+    return { triggered: false, recentDenials: recentDenials.length, threshold: denyThreshold };
+  }
+
+  // Threshold exceeded — trigger self-heal
+  let healResult = null;
+  try {
+    const { runSelfHeal } = require('./self-heal');
+    const uniqueGates = [...new Set(recentDenials.map(d => d.gateId).filter(Boolean))];
+    healResult = runSelfHeal({
+      reason: `audit-trail: ${recentDenials.length} denials in ${windowMs / 1000}s (gates: ${uniqueGates.join(', ')})`,
+    });
+  } catch {
+    healResult = { error: 'self-heal module unavailable' };
+  }
+
+  return {
+    triggered: true,
+    recentDenials: recentDenials.length,
+    threshold: denyThreshold,
+    gates: [...new Set(recentDenials.map(d => d.gateId).filter(Boolean))],
+    healResult,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Semantic cache threshold auto-tuning
+// ---------------------------------------------------------------------------
+
+const CACHE_TUNE_STATE_FILENAME = 'cache-tune-state.json';
+
+/**
+ * Auto-tunes THUMBGATE_SEMANTIC_CACHE_THRESHOLD based on audit trail feedback.
+ * If deny rate is high → tighten cache (raise threshold, fewer false hits).
+ * If deny rate is low → loosen cache (lower threshold, more cache hits).
+ *
+ * @param {string} [logPath]
+ * @returns {{ currentThreshold: number, recommendedThreshold: number, denyRate: number, applied: boolean }}
+ */
+function tuneCacheThreshold(logPath) {
+  const stats = auditStats(logPath);
+  const total = stats.total || 1;
+  const denyRate = stats.deny / total;
+
+  const currentThreshold = parseFloat(process.env.THUMBGATE_SEMANTIC_CACHE_THRESHOLD || '0.7');
+  const MIN_THRESHOLD = 0.5;
+  const MAX_THRESHOLD = 0.95;
+  const STEP = 0.02;
+
+  // High deny rate (>20%) → agent is hitting gates often → tighten cache to reduce hallucinated recalls
+  // Low deny rate (<5%) → agent is compliant → loosen cache for more hits and cost savings
+  let recommended = currentThreshold;
+  if (denyRate > 0.20) {
+    recommended = Math.min(currentThreshold + STEP, MAX_THRESHOLD);
+  } else if (denyRate < 0.05 && total > 10) {
+    recommended = Math.max(currentThreshold - STEP, MIN_THRESHOLD);
+  }
+  recommended = Math.round(recommended * 100) / 100;
+
+  // Persist tuning state
+  const statePath = path.join(path.dirname(getAuditLogPath()), CACHE_TUNE_STATE_FILENAME);
+  const tuneRecord = {
+    timestamp: new Date().toISOString(),
+    currentThreshold,
+    recommendedThreshold: recommended,
+    denyRate: Math.round(denyRate * 10000) / 100,
+    totalEvents: stats.total,
+  };
+
+  try {
+    ensureDir(path.dirname(statePath));
+    fs.writeFileSync(statePath, JSON.stringify(tuneRecord, null, 2) + '\n');
+  } catch { /* non-critical */ }
+
+  return {
+    currentThreshold,
+    recommendedThreshold: recommended,
+    denyRate: Math.round(denyRate * 10000) / 100,
+    applied: recommended !== currentThreshold,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  recordAuditEvent,
+  auditToFeedback,
+  readAuditLog,
+  auditStats,
+  latencyStats,
+  skillAdherence,
+  evaluateSelfHealTrigger,
+  tuneCacheThreshold,
+  getAuditLogPath,
+  sanitizeToolInput,
+  AUDIT_LOG_FILENAME,
+  CACHE_TUNE_STATE_FILENAME,
+};
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute latency statistics from audit trail entries that have latencyMs.
+ * @param {string} [logPath]
+ * @returns {{ count: number, avgMs: number, p50Ms: number, p95Ms: number, p99Ms: number, maxMs: number, slowest: Array }}
+ */
+function latencyStats(logPath) {
+  const entries = readAuditLog(logPath);
+  const withLatency = entries.filter(e => typeof e.latencyMs === 'number');
+  if (withLatency.length === 0) return { count: 0, avgMs: 0, p50Ms: 0, p95Ms: 0, p99Ms: 0, maxMs: 0, slowest: [] };
+
+  const sorted = withLatency.map(e => e.latencyMs).sort((a, b) => a - b);
+  const sum = sorted.reduce((a, b) => a + b, 0);
+  const percentile = (arr, p) => arr[Math.min(Math.ceil(arr.length * p) - 1, arr.length - 1)];
+
+  // Per-tool breakdown
+  const byTool = {};
+  for (const e of withLatency) {
+    const tool = e.toolName || 'unknown';
+    if (!byTool[tool]) byTool[tool] = [];
+    byTool[tool].push(e.latencyMs);
+  }
+  const toolStats = {};
+  for (const [tool, latencies] of Object.entries(byTool)) {
+    const s = latencies.sort((a, b) => a - b);
+    toolStats[tool] = {
+      count: s.length,
+      avgMs: Math.round(s.reduce((a, b) => a + b, 0) / s.length),
+      p95Ms: percentile(s, 0.95),
+      maxMs: s[s.length - 1],
+    };
+  }
+
+  // Top 5 slowest calls
+  const slowest = withLatency
+    .sort((a, b) => b.latencyMs - a.latencyMs)
+    .slice(0, 5)
+    .map(e => ({ tool: e.toolName, latencyMs: e.latencyMs, timestamp: e.timestamp }));
+
+  return {
+    count: sorted.length,
+    avgMs: Math.round(sum / sorted.length),
+    p50Ms: percentile(sorted, 0.50),
+    p95Ms: percentile(sorted, 0.95),
+    p99Ms: percentile(sorted, 0.99),
+    maxMs: sorted[sorted.length - 1],
+    byTool: toolStats,
+    slowest,
+  };
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.includes('--stats')) {
+    console.log(JSON.stringify(auditStats(), null, 2));
+  } else if (args.includes('--adherence')) {
+    console.log(JSON.stringify(skillAdherence(), null, 2));
+  } else if (args.includes('--self-heal')) {
+    console.log(JSON.stringify(evaluateSelfHealTrigger(), null, 2));
+  } else if (args.includes('--tune-cache')) {
+    console.log(JSON.stringify(tuneCacheThreshold(), null, 2));
+  } else if (args.includes('--latency')) {
+    console.log(JSON.stringify(latencyStats(), null, 2));
+  } else {
+    const entries = readAuditLog();
+    const adherence = skillAdherence();
+    console.log(`Audit trail: ${entries.length} entries`);
+    const stats = auditStats();
+    console.log(`  allow: ${stats.allow}  warn: ${stats.warn}  deny: ${stats.deny}`);
+    console.log(`  skill adherence: ${adherence.overall}% across ${adherence.totalTools} tools`);
+    const lat = latencyStats();
+    if (lat.count > 0) {
+      console.log(`  latency: avg=${lat.avgMs}ms  p95=${lat.p95Ms}ms  max=${lat.maxMs}ms  (${lat.count} samples)`);
+    }
+  }
+}

package/scripts/auto-promote-gates.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_AUTO_GATES = 10;
+const WARN_THRESHOLD = 3; // 3+ repeated failures surface a warning gate
+const BLOCK_THRESHOLD = 5; // 5+ repeated failures hard-block the action
+const WINDOW_DAYS = 30;
+
+const NEG_SIGNALS = new Set(['negative', 'negative_strong', 'down', 'thumbs_down']);
+
+function getFeedbackLogPath() {
+  if (process.env.THUMBGATE_FEEDBACK_DIR) {
+    return path.join(process.env.THUMBGATE_FEEDBACK_DIR, 'feedback-log.jsonl');
+  }
+  const localFallback = path.join(process.cwd(), '.thumbgate', 'feedback-log.jsonl');
+  const localClaude = path.join(process.cwd(), '.claude', 'memory', 'feedback', 'feedback-log.jsonl');
+  if (fs.existsSync(localFallback)) return localFallback;
+  if (fs.existsSync(localClaude)) return localClaude;
+  return localFallback; // default even if doesn't exist
+}
+
+function getAutoGatesPath() {
+  return path.join(path.dirname(getFeedbackLogPath()), 'auto-promoted-gates.json');
+}
+
+function readJSONL(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const raw = fs.readFileSync(filePath, 'utf-8').trim();
+  if (!raw) return [];
+  return raw.split('\n').map((line) => {
+    try { return JSON.parse(line); } catch { return null; }
+  }).filter(Boolean);
+}
+
+function loadAutoGates() {
+  const autoGatesPath = getAutoGatesPath();
+  if (!fs.existsSync(autoGatesPath)) {
+    return { version: 1, gates: [], promotionLog: [] };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(autoGatesPath, 'utf-8'));
+  } catch {
+    return { version: 1, gates: [], promotionLog: [] };
+  }
+}
+
+function saveAutoGates(data) {
+  const autoGatesPath = getAutoGatesPath();
+  const dir = path.dirname(autoGatesPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(autoGatesPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+function isNegative(entry) {
+  const sig = (entry.signal || entry.feedback || '').toLowerCase();
+  return NEG_SIGNALS.has(sig);
+}
+
+function extractPatternKey(entry) {
+  // Use tags as primary grouping key; fall back to context normalization
+  const tags = (entry.tags || []).filter((t) => !['feedback', 'negative', 'positive'].includes(t));
+  if (tags.length > 0) return tags.sort().join('+');
+
+  const ctx = (entry.context || entry.whatWentWrong || '').toLowerCase().trim();
+  if (ctx.length < 10) return null;
+  // Normalize paths and numbers for grouping
+  return ctx.replace(/\/Users\/[^\s/]+/g, '~').replace(/:[0-9]+/g, '').replace(/\s+/g, ' ').slice(0, 100);
+}
+
+function extractDiagnosticKeys(entry) {
+  const keys = [];
+  const diagnosis = entry && entry.diagnosis ? entry.diagnosis : null;
+  if (!diagnosis) return keys;
+
+  if (diagnosis.rootCauseCategory) {
+    keys.push(`diagnosis:${diagnosis.rootCauseCategory}`);
+  }
+
+  const violations = Array.isArray(diagnosis.violations) ? diagnosis.violations : [];
+  violations.slice(0, 3).forEach((violation) => {
+    const key = violation.constraintId || violation.message;
+    if (key) {
+      keys.push(`constraint:${key}`);
+    }
+  });
+
+  return keys;
+}
+
+function groupNegativeFeedback(entries, windowDays) {
+  const cutoff = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+  const groups = {};
+
+  for (const entry of entries) {
+    if (!isNegative(entry)) continue;
+
+    const ts = entry.timestamp ? new Date(entry.timestamp).getTime() : 0;
+    if (ts < cutoff) continue;
+
+    const keys = [extractPatternKey(entry), ...extractDiagnosticKeys(entry)]
+      .filter(Boolean)
+      .filter((value, index, values) => values.indexOf(value) === index);
+    if (keys.length === 0) continue;
+
+    for (const key of keys) {
+      if (!groups[key]) {
+        groups[key] = {
+          key,
+          count: 0,
+          entries: [],
+          latestContext: '',
+          latestTimestamp: '',
+        };
+      }
+      groups[key].count++;
+      groups[key].entries.push(entry);
+      if (!groups[key].latestTimestamp || (entry.timestamp && entry.timestamp > groups[key].latestTimestamp)) {
+        groups[key].latestTimestamp = entry.timestamp || '';
+        groups[key].latestContext = entry.context || entry.whatWentWrong || '';
+      }
+    }
+  }
+
+  return groups;
+}
+
+function patternToGateId(key) {
+  return 'auto-' + key.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').slice(0, 50).toLowerCase();
+}
+
+function buildGateRule(group) {
+  const action = group.count === 'MANUAL' ? group.manualAction || 'block' : (group.count >= BLOCK_THRESHOLD ? 'block' : 'warn');
+  const severity = action === 'block' ? 'critical' : 'medium';
+  const context = group.latestContext.slice(0, 120);
+  const kind = group.key.startsWith('diagnosis:')
+    ? 'repeated diagnosis'
+    : group.key.startsWith('constraint:')
+      ? 'repeated constraint violation'
+      : 'repeated pattern';
+  
+  const occurrencesText = group.count === 'MANUAL' ? 'manual' : `${group.count} occurrences`;
+  const suggestedMessage = `Auto-promoted ${kind}: "${context}" (${occurrencesText} in ${WINDOW_DAYS} days)`;
+
+  return {
+    id: patternToGateId(group.key),
+    trigger: `auto:${group.key}`,
+    pattern: group.key.replace(/^diagnosis:|constraint:/, ''),
+    action,
+    message: suggestedMessage,
+    severity,
+    occurrences: group.count,
+    promotedAt: new Date().toISOString(),
+    source: group.source || 'auto-promote',
+  };
+}
+
+function forcePromote(context, action = 'block') {
+  if (!context) throw new Error('context is required for force-promote');
+  const data = loadAutoGates();
+  const gateId = patternToGateId(context);
+  
+  // Remove existing if any
+  data.gates = data.gates.filter(g => g.id !== gateId);
+  
+  const gate = buildGateRule({
+    key: context,
+    latestContext: context,
+    count: 'MANUAL',
+    manualAction: action,
+    source: 'force-promote'
+  });
+  data.gates.unshift(gate);
+  
+  if (data.gates.length > MAX_AUTO_GATES) {
+    data.gates = data.gates.slice(0, MAX_AUTO_GATES);
+  }
+
+  data.promotionLog = data.promotionLog || [];
+  data.promotionLog.push({
+    gateId,
+    context,
+    action,
+    promotedAt: new Date().toISOString(),
+    source: 'force-promote'
+  });
+
+  saveAutoGates(data);
+  return { gateId, action, totalGates: data.gates.length };
+}
+
+function promote(feedbackLogPath) {
+  const logPath = feedbackLogPath || getFeedbackLogPath();
+  const entries = readJSONL(logPath);
+  const groups = groupNegativeFeedback(entries, WINDOW_DAYS);
+  const data = loadAutoGates();
+  const existingIds = new Set(data.gates.map((g) => g.id));
+  const promotions = [];
+
+  for (const group of Object.values(groups)) {
+    if (group.count < WARN_THRESHOLD) continue;
+
+    const gateId = patternToGateId(group.key);
+
+    // Check for existing gate — possibly upgrade
+    const existingIdx = data.gates.findIndex((g) => g.id === gateId);
+    if (existingIdx !== -1) {
+      const existing = data.gates[existingIdx];
+      const newAction = group.count >= BLOCK_THRESHOLD ? 'block' : 'warn';
+      if (existing.action !== newAction && newAction === 'block') {
+        // Upgrade from warn to block
+        data.gates[existingIdx] = { ...existing, action: 'block', severity: 'critical', occurrences: group.count, upgradedAt: new Date().toISOString() };
+        promotions.push({ type: 'upgrade', gateId, from: existing.action, to: 'block', occurrences: group.count });
+      }
+      // Update occurrence count even if no action change
+      data.gates[existingIdx].occurrences = group.count;
+      continue;
+    }
+
+    // New gate
+    const gate = buildGateRule(group);
+
+    // Enforce max limit — rotate oldest
+    if (data.gates.length >= MAX_AUTO_GATES) {
+      const removed = data.gates.shift();
+      promotions.push({ type: 'rotated', removedGateId: removed.id });
+    }
+
+    data.gates.push(gate);
+    promotions.push({ type: 'new', gateId: gate.id, action: gate.action, occurrences: group.count });
+  }
+
+  // Log promotions
+  for (const p of promotions) {
+    data.promotionLog = data.promotionLog || [];
+    data.promotionLog.push({ ...p, timestamp: new Date().toISOString() });
+  }
+
+  saveAutoGates(data);
+
+  return { promotions, totalGates: data.gates.length, data };
+}
+
+function runCli(argv = process.argv.slice(2)) {
+  const forceContext = argv.find((arg) => arg.startsWith('--force-block='))?.split('=')[1];
+  if (forceContext) {
+    const result = forcePromote(forceContext, 'block');
+    console.log(`Forced block gate created: ${result.gateId}`);
+    console.log(`Total auto-promoted gates: ${result.totalGates}`);
+    return 0;
+  }
+
+  const logPath = argv[0] && !argv[0].startsWith('--') ? argv[0] : undefined;
+  const result = promote(logPath);
+  if (result.promotions.length === 0) {
+    console.log('No new promotions.');
+  } else {
+    for (const promotion of result.promotions) {
+      if (promotion.type === 'new') {
+        console.log(`NEW gate: ${promotion.gateId} (${promotion.action}, ${promotion.occurrences} occurrences)`);
+      } else if (promotion.type === 'upgrade') {
+        console.log(`UPGRADE: ${promotion.gateId} ${promotion.from} -> ${promotion.to} (${promotion.occurrences} occurrences)`);
+      } else if (promotion.type === 'rotated') {
+        console.log(`ROTATED out: ${promotion.removedGateId}`);
+      }
+    }
+  }
+  console.log(`Total auto-promoted gates: ${result.totalGates}`);
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = runCli();
+  } catch (err) {
+    console.error('auto-promote-gates error:', err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  promote,
+  forcePromote,
+  runCli,
+  loadAutoGates,
+  saveAutoGates,
+  getAutoGatesPath,
+  groupNegativeFeedback,
+  patternToGateId,
+  buildGateRule,
+  extractPatternKey,
+  isNegative,
+  MAX_AUTO_GATES,
+  WARN_THRESHOLD,
+  BLOCK_THRESHOLD,
+  WINDOW_DAYS,
+};