thumbgate 1.4.1 → 1.4.3

package/scripts/cli-status.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * cli-status.js — agent-friendly health check for ThumbGate.
+ *
+ * Combines feedback stats, gate stats, lesson count, and agent detection
+ * into a single JSON-friendly payload.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function detectAgent(projectDir) {
+  if (fs.existsSync(path.join(projectDir, '.claude'))) return 'claude-code';
+  if (fs.existsSync(path.join(projectDir, '.cursorrules'))) return 'cursor';
+  if (fs.existsSync(path.join(projectDir, '.cursor'))) return 'cursor';
+  if (fs.existsSync(path.join(projectDir, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(projectDir, '.gemini'))) return 'gemini';
+  if (fs.existsSync(path.join(projectDir, '.amp'))) return 'amp';
+  return null;
+}
+
+function generateAgentStatus(options = {}) {
+  const PKG_ROOT = options.pkgRoot || path.join(__dirname, '..');
+  const projectDir = options.projectDir || process.cwd();
+
+  // Feedback paths
+  const { getFeedbackPaths, readJSONL, analyzeFeedback } = require(path.join(PKG_ROOT, 'scripts', 'feedback-loop'));
+  const paths = getFeedbackPaths();
+
+  // Feedback entries
+  const feedbackEntries = readJSONL(paths.FEEDBACK_LOG_PATH);
+  const memoryEntries = readJSONL(paths.MEMORY_LOG_PATH);
+
+  // Gate stats
+  let gateData = { totalGates: 0, autoPromotedGates: 0, manualGates: 0, totalBlocked: 0 };
+  try {
+    const { calculateStats } = require(path.join(PKG_ROOT, 'scripts', 'gate-stats'));
+    gateData = calculateStats();
+  } catch { /* gate-stats not available */ }
+
+  // Prevention rules count
+  let preventionRuleCount = 0;
+  if (fs.existsSync(paths.PREVENTION_RULES_PATH)) {
+    const rulesContent = fs.readFileSync(paths.PREVENTION_RULES_PATH, 'utf-8');
+    const ruleHeaders = rulesContent.match(/^## /gm);
+    preventionRuleCount = ruleHeaders ? ruleHeaders.length : 0;
+  }
+
+  // Last feedback timestamp
+  const lastFeedback = feedbackEntries.length > 0
+    ? feedbackEntries[feedbackEntries.length - 1]
+    : null;
+  const lastFeedbackTimestamp = lastFeedback
+    ? (lastFeedback.timestamp || lastFeedback.createdAt || null)
+    : null;
+
+  // Agent detection
+  const agent = detectAgent(projectDir);
+
+  // Enforcement check: is there at least one blocking gate?
+  const hasBlockingGates = gateData.totalGates > 0;
+  const hasPreToolHook = (() => {
+    try {
+      const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      return Boolean(
+        settings.hooks &&
+        settings.hooks.PreToolUse &&
+        settings.hooks.PreToolUse.length > 0
+      );
+    } catch { return false; }
+  })();
+  const enforcementActive = hasBlockingGates || hasPreToolHook;
+
+  // Config
+  const configPath = path.join(projectDir, '.thumbgate', 'config.json');
+  let config = null;
+  try {
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+  } catch { /* ignore */ }
+
+  // Version
+  let version = 'unknown';
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+  } catch { /* ignore */ }
+
+  return {
+    version,
+    agent,
+    enforcementActive,
+    gates: {
+      total: gateData.totalGates,
+      manual: gateData.manualGates,
+      autoPromoted: gateData.autoPromotedGates,
+      blocking: gateData.blockGates || 0,
+      warning: gateData.warnGates || 0,
+    },
+    lessons: memoryEntries.length,
+    feedback: {
+      total: feedbackEntries.length,
+      positive: feedbackEntries.filter(e => e.signal === 'positive').length,
+      negative: feedbackEntries.filter(e => e.signal === 'negative').length,
+    },
+    preventionRules: preventionRuleCount,
+    lastFeedbackTimestamp,
+    feedbackDir: paths.FEEDBACK_DIR,
+    initialized: Boolean(config),
+  };
+}
+
+function formatStatus(data) {
+  const BD = '\x1b[1m';
+  const RST = '\x1b[0m';
+  const G = '\x1b[32m';
+  const R = '\x1b[31m';
+  const C = '\x1b[36m';
+  const Y = '\x1b[33m';
+  const D = '\x1b[90m';
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate status${RST}  v${data.version}`);
+  lines.push('─'.repeat(50));
+
+  // Scope badge
+  const scope = '[LOCAL]';
+  lines.push(`  ${C}${scope}${RST} ${data.feedbackDir}`);
+  lines.push('');
+
+  // Core metrics
+  const enfBadge = data.enforcementActive
+    ? `${G}[ACTIVE]${RST}`
+    : `${Y}[LEARNING]${RST}`;
+  lines.push(`  Enforcement     : ${enfBadge}`);
+  lines.push(`  Agent           : ${data.agent || 'none detected'}`);
+  lines.push(`  Gates           : ${data.gates.total} (${data.gates.blocking} block, ${data.gates.warning} warn)`);
+  lines.push(`  Lessons         : ${data.lessons}`);
+  lines.push(`  Prevention Rules: ${data.preventionRules}`);
+  lines.push('');
+  lines.push(`  Feedback        : ${data.feedback.total} total (${G}${data.feedback.positive} up${RST}, ${R}${data.feedback.negative} down${RST})`);
+  if (data.lastFeedbackTimestamp) {
+    const ago = relativeTime(data.lastFeedbackTimestamp);
+    lines.push(`  Last Feedback   : ${ago} ${D}(${data.lastFeedbackTimestamp})${RST}`);
+  } else {
+    lines.push(`  Last Feedback   : ${D}none${RST}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function relativeTime(ts) {
+  if (!ts) return '';
+  const d = Math.floor((Date.now() - new Date(ts).getTime()) / 86400000);
+  if (d === 0) return 'today';
+  if (d === 1) return '1 day ago';
+  return `${d} days ago`;
+}
+
+module.exports = { generateAgentStatus, formatStatus };

package/scripts/cross-encoder-reranker.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Cross-Encoder Reranker for ThumbGate lesson retrieval.
+ *
+ * Two-stage retrieval:
+ *   Stage 1: Fast candidate retrieval (existing bigram Jaccard + keyword matching)
+ *   Stage 2: Cross-encoder reranking scores query-document pairs jointly
+ *
+ * The cross-encoder evaluates the query AND each lesson together (not independently),
+ * catching false positives that keyword/vector search misses.
+ *
+ * Architecture reference: "Advanced RAG Retrieval: Cross-Encoders & Reranking"
+ * (Towards Data Science, April 2026)
+ *
+ * When LLM is available (ANTHROPIC_API_KEY), uses Claude as the cross-encoder.
+ * Falls back to enhanced heuristic scoring when LLM is unavailable.
+ */
+
+const { retrieveRelevantLessons, scoreRelevance, buildActionSignature } = require('./lesson-retrieval');
+
+/**
+ * Heuristic cross-encoder: scores a (query, document) pair jointly.
+ * Unlike bi-encoder (independent embeddings), this examines the pair together
+ * to find semantic relationships that keyword matching misses.
+ */
+function heuristicCrossEncode(query, document) {
+  const queryLower = (query || '').toLowerCase();
+  const docLower = (document || '').toLowerCase();
+
+  let score = 0;
+
+  // 1. Exact substring containment (strongest signal)
+  if (queryLower.length > 3 && docLower.length > 3 &&
+      (docLower.includes(queryLower) || queryLower.includes(docLower))) {
+    score += 0.9;
+    return Math.min(score, 1);
+  }
+
+  // 2. Shared noun phrases (not just tokens — consecutive word pairs)
+  const queryPhrases = extractPhrases(queryLower);
+  const docPhrases = extractPhrases(docLower);
+  const phraseOverlap = queryPhrases.filter((p) => docPhrases.includes(p));
+  score += Math.min(phraseOverlap.length * 0.15, 0.5);
+
+  // 3. Semantic category matching
+  const categories = {
+    destructive: ['delete', 'remove', 'drop', 'destroy', 'wipe', 'truncate', 'rm -rf', 'force-push', 'reset --hard'],
+    git: ['git', 'push', 'pull', 'merge', 'rebase', 'branch', 'commit', 'checkout', 'stash'],
+    database: ['sql', 'query', 'table', 'migration', 'schema', 'database', 'insert', 'update', 'select'],
+    deploy: ['deploy', 'release', 'publish', 'railway', 'vercel', 'heroku', 'npm publish'],
+    security: ['secret', 'token', 'api key', 'password', 'credential', 'env', '.env', 'pem'],
+    file: ['edit', 'write', 'create', 'modify', 'config', 'package.json', 'readme'],
+  };
+
+  for (const [, terms] of Object.entries(categories)) {
+    const queryHit = terms.some((t) => queryLower.includes(t));
+    const docHit = terms.some((t) => docLower.includes(t));
+    if (queryHit && docHit) {
+      score += 0.25;
+      break; // Only count strongest category match
+    }
+  }
+
+  // 4. Action-target alignment (e.g., "git push" in query matches "push to main" in doc)
+  const queryVerbs = extractVerbs(queryLower);
+  const docVerbs = extractVerbs(docLower);
+  const verbOverlap = queryVerbs.filter((v) => docVerbs.includes(v));
+  score += Math.min(verbOverlap.length * 0.1, 0.3);
+
+  // 5. Negation alignment (both about what NOT to do)
+  const queryNegated = /\b(don'?t|never|avoid|block|prevent|stop)\b/.test(queryLower);
+  const docNegated = /\b(don'?t|never|avoid|block|prevent|stop)\b/.test(docLower);
+  if (queryNegated && docNegated) score += 0.1;
+
+  return Math.min(score, 1);
+}
+
+/**
+ * LLM cross-encoder: uses Claude to score relevance of query-document pairs.
+ * More accurate but requires API key and costs tokens.
+ */
+async function llmCrossEncode(query, documents) {
+  const { isAvailable, callClaude, MODELS } = require('./llm-client');
+  if (!isAvailable()) return null;
+
+  const docList = documents
+    .map((d, i) => `[${i}] ${(d.title || '').slice(0, 100)} | ${(d.content || '').slice(0, 200)}`)
+    .join('\n');
+
+  const prompt = `You are a relevance scoring engine. Given a query and a list of documents, score each document's relevance to the query from 0.0 (irrelevant) to 1.0 (highly relevant).
+
+Query: "${query.slice(0, 300)}"
+
+Documents:
+${docList}
+
+Return ONLY a JSON array of scores, one per document. Example: [0.9, 0.2, 0.7, 0.1, 0.5]
+No other text.`;
+
+  try {
+    const raw = await callClaude({
+      systemPrompt: 'You are a relevance scoring engine. Return only JSON arrays of numbers.',
+      userPrompt: prompt,
+      model: MODELS.FAST,
+      maxTokens: 256,
+    });
+    const scores = JSON.parse(raw);
+    if (Array.isArray(scores) && scores.length === documents.length) {
+      return scores.map((s) => Math.max(0, Math.min(1, Number(s) || 0)));
+    }
+  } catch { /* fall back to heuristic */ }
+  return null;
+}
+
+/**
+ * Two-stage retrieval with cross-encoder reranking.
+ *
+ * Stage 1: Retrieve top N candidates using existing keyword + bigram matching
+ * Stage 2: Rerank candidates using cross-encoder (LLM or heuristic)
+ * Return top K results by cross-encoder score
+ */
+async function retrieveWithReranking(toolName, actionContext, options = {}) {
+  const {
+    candidateCount = 20,
+    maxResults = 5,
+    useLLM = false,
+    feedbackDir,
+  } = options;
+
+  // Stage 1: Fast candidate retrieval (existing system)
+  const candidates = retrieveRelevantLessons(toolName, actionContext, {
+    maxResults: candidateCount,
+    feedbackDir,
+  });
+
+  if (candidates.length === 0) return [];
+  if (candidates.length <= maxResults) return candidates;
+
+  const query = `${toolName || ''} ${actionContext || ''}`.trim();
+
+  // Stage 2: Cross-encoder reranking
+  let rerankedScores;
+
+  if (useLLM) {
+    rerankedScores = await llmCrossEncode(query, candidates);
+  }
+
+  // Fall back to heuristic cross-encoder if LLM unavailable or failed
+  if (!rerankedScores) {
+    rerankedScores = candidates.map((c) => {
+      const docText = `${c.title || ''} ${c.content || ''}`;
+      return heuristicCrossEncode(query, docText);
+    });
+  }
+
+  // Combine original relevance score with cross-encoder score
+  // Weight: 40% original, 60% cross-encoder (cross-encoder is more precise)
+  const reranked = candidates.map((c, i) => ({
+    ...c,
+    crossEncoderScore: rerankedScores[i],
+    combinedScore: c.relevanceScore * 0.4 + rerankedScores[i] * 0.6,
+  }));
+
+  return reranked
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, maxResults);
+}
+
+/**
+ * Synchronous version for use in PreToolUse hooks (cannot be async).
+ */
+function retrieveWithRerankingSync(toolName, actionContext, options = {}) {
+  const {
+    candidateCount = 20,
+    maxResults = 5,
+    feedbackDir,
+  } = options;
+
+  const candidates = retrieveRelevantLessons(toolName, actionContext, {
+    maxResults: candidateCount,
+    feedbackDir,
+  });
+
+  if (candidates.length === 0) return [];
+  if (candidates.length <= maxResults) return candidates;
+
+  const query = `${toolName || ''} ${actionContext || ''}`.trim();
+
+  const rerankedScores = candidates.map((c) => {
+    const docText = `${c.title || ''} ${c.content || ''}`;
+    return heuristicCrossEncode(query, docText);
+  });
+
+  const reranked = candidates.map((c, i) => ({
+    ...c,
+    crossEncoderScore: rerankedScores[i],
+    combinedScore: c.relevanceScore * 0.4 + rerankedScores[i] * 0.6,
+  }));
+
+  return reranked
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, maxResults);
+}
+
+// --- Utility functions ---
+
+function extractPhrases(text) {
+  const words = text.split(/\s+/).filter((w) => w.length > 2);
+  const phrases = [];
+  for (let i = 0; i < words.length - 1; i++) {
+    phrases.push(`${words[i]} ${words[i + 1]}`);
+  }
+  return phrases;
+}
+
+function extractVerbs(text) {
+  const verbPatterns = [
+    'push', 'pull', 'merge', 'delete', 'create', 'edit', 'write', 'read',
+    'deploy', 'install', 'remove', 'run', 'execute', 'build', 'test',
+    'commit', 'rebase', 'reset', 'drop', 'truncate', 'migrate', 'publish',
+    'block', 'allow', 'approve', 'deny', 'warn', 'log',
+  ];
+  return verbPatterns.filter((v) => text.includes(v));
+}
+
+module.exports = {
+  heuristicCrossEncode,
+  llmCrossEncode,
+  retrieveWithReranking,
+  retrieveWithRerankingSync,
+  extractPhrases,
+  extractVerbs,
+};

package/scripts/explore-subcommands.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * explore-subcommands.js — non-interactive explore for agent consumption.
+ *
+ * Supports:
+ *   thumbgate explore lessons [--json] [--limit=N]
+ *   thumbgate explore rules   [--json]
+ *   thumbgate explore gates   [--json]
+ *
+ * When --json is passed, outputs structured data. Otherwise renders
+ * human-readable tables with context signal badges.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BD = '\x1b[1m';
+const RST = '\x1b[0m';
+const G = '\x1b[32m';
+const R = '\x1b[31m';
+const C = '\x1b[36m';
+const Y = '\x1b[33m';
+const D = '\x1b[90m';
+
+function relDate(ts) {
+  if (!ts) return '';
+  const d = Math.floor((Date.now() - new Date(ts).getTime()) / 86400000);
+  if (d === 0) return 'today';
+  if (d === 1) return '1d ago';
+  return `${d}d ago`;
+}
+
+function confidenceBadge(lesson) {
+  // Derive confidence from signal + whether it became a gate
+  const signal = (lesson.signal || lesson.feedback || '').toLowerCase();
+  if (lesson.gatePromoted || lesson.autoGateId) return `${G}[ACTIVE]${RST}`;
+  if (signal.includes('negative') || signal === 'down') return `${Y}[LEARNING]${RST}`;
+  return `${D}[LEARNING]${RST}`;
+}
+
+function scopeBadge() {
+  return `${C}[LOCAL]${RST}`;
+}
+
+function actionBadge(action) {
+  if (action === 'block') return `${R}[BLOCKED]${RST}`;
+  if (action === 'warn') return `${Y}[WARN]${RST}`;
+  return `${G}[ALLOWED]${RST}`;
+}
+
+// ---------------------------------------------------------------------------
+// Data loaders (reuse from explore.js patterns)
+// ---------------------------------------------------------------------------
+
+function loadLessons(feedbackDir) {
+  const p = path.join(feedbackDir, 'memory-log.jsonl');
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).map(l => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean).reverse();
+}
+
+function loadGates(pkgRoot) {
+  const gatesDir = path.join(pkgRoot, 'config', 'gates');
+  const gates = [];
+  if (!fs.existsSync(gatesDir)) return gates;
+  for (const f of fs.readdirSync(gatesDir).sort((a, b) => a.localeCompare(b))) {
+    if (!f.endsWith('.json') || f === 'custom.json') continue;
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(gatesDir, f), 'utf8'));
+      const items = Array.isArray(raw) ? raw : (raw.gates || raw.rules || [raw]);
+      items.forEach(g => gates.push({ ...g, _file: f }));
+    } catch { /* skip */ }
+  }
+  // Auto-promoted gates
+  try {
+    const { loadAutoGates } = require(path.join(pkgRoot, 'scripts', 'auto-promote-gates'));
+    const auto = loadAutoGates();
+    (auto.gates || []).forEach(g => gates.push({ ...g, _file: 'auto-promoted', _auto: true }));
+  } catch { /* ok */ }
+  return gates;
+}
+
+function loadRules(feedbackDir) {
+  const p = path.join(feedbackDir, 'prevention-rules.md');
+  if (!fs.existsSync(p)) return [];
+  const content = fs.readFileSync(p, 'utf8');
+  // Split on ## headers; the first segment is the preamble (before any ##), skip it
+  const parts = content.split(/^## /m);
+  const ruleSections = parts.slice(1).filter(Boolean);
+  return ruleSections.map((section, i) => {
+    const lines = section.trim().split('\n');
+    const title = lines[0] || `Rule ${i + 1}`;
+    const body = lines.slice(1).join('\n').trim();
+    return { id: i + 1, title: title.trim(), body };
+  });
+}
+
+function loadGateFirings(feedbackDir) {
+  const p = path.join(feedbackDir, 'rejection-ledger.jsonl');
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).map(l => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean).reverse();
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+function exploreLessons(options = {}) {
+  const { feedbackDir, limit = 20, json = false } = options;
+  const lessons = loadLessons(feedbackDir).slice(0, limit);
+
+  if (json) {
+    const payload = lessons.map(l => ({
+      id: l.id,
+      signal: l.signal || l.feedback,
+      context: l.content || l.context || '',
+      tags: l.tags || [],
+      domain: l.domain || null,
+      importance: l.importance || 'medium',
+      timestamp: l.timestamp || l.createdAt,
+      scope: 'local',
+      confidence: (l.gatePromoted || l.autoGateId) ? 'active' : 'learning',
+    }));
+    return { lessons: payload, total: payload.length, scope: 'local' };
+  }
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate explore lessons${RST}  ${scopeBadge()}`);
+  lines.push('─'.repeat(60));
+
+  if (lessons.length === 0) {
+    lines.push('  No lessons stored yet. Capture feedback to create lessons.');
+    lines.push('  Run: npx thumbgate capture --feedback=down --context="what failed"');
+  }
+
+  for (const l of lessons) {
+    const sig = (l.signal || l.feedback || '').toLowerCase();
+    const icon = sig.includes('positive') || sig === 'up' ? `${G}+${RST}` : `${R}-${RST}`;
+    const badge = confidenceBadge(l);
+    const context = (l.content || l.context || '').slice(0, 70);
+    const ts = relDate(l.timestamp || l.createdAt);
+    const tags = (l.tags || []).join(', ');
+    lines.push(`  ${icon} ${badge} ${context}`);
+    if (tags || ts) {
+      lines.push(`    ${D}${ts}${tags ? '  tags: ' + tags : ''}${RST}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function exploreRules(options = {}) {
+  const { feedbackDir, json = false } = options;
+  const rules = loadRules(feedbackDir);
+
+  if (json) {
+    const payload = rules.map(r => ({
+      id: r.id,
+      title: r.title,
+      body: r.body,
+      scope: 'local',
+    }));
+    return { rules: payload, total: payload.length, scope: 'local' };
+  }
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate explore rules${RST}  ${scopeBadge()}`);
+  lines.push('─'.repeat(60));
+
+  if (rules.length === 0) {
+    lines.push('  No prevention rules generated yet.');
+    lines.push('  Run: npx thumbgate rules');
+  }
+
+  for (const r of rules) {
+    lines.push(`  ${Y}Rule ${r.id}${RST}: ${r.title}`);
+    if (r.body) {
+      const preview = r.body.split('\n')[0].slice(0, 80);
+      lines.push(`    ${D}${preview}${RST}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function exploreGates(options = {}) {
+  const { pkgRoot, json = false } = options;
+  const gates = loadGates(pkgRoot || path.join(__dirname, '..'));
+
+  if (json) {
+    const payload = gates.map(g => ({
+      id: g.id || g.name || 'unnamed',
+      pattern: g.pattern || g.toolName || '',
+      action: g.action || 'warn',
+      occurrences: g.occurrences || 0,
+      source: g._auto ? 'auto-promoted' : (g._file || 'manual'),
+      scope: 'local',
+      status: g.action === 'block' ? 'blocked' : 'allowed',
+    }));
+    return { gates: payload, total: payload.length, scope: 'local' };
+  }
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate explore gates${RST}  ${scopeBadge()}`);
+  lines.push('─'.repeat(60));
+
+  if (gates.length === 0) {
+    lines.push('  No gates configured. Run: npx thumbgate init');
+  }
+
+  for (const g of gates) {
+    const name = g.id || g.name || 'unnamed';
+    const badge = actionBadge(g.action);
+    const source = g._auto ? 'auto' : g._file || 'manual';
+    const occ = g.occurrences ? ` (${g.occurrences} fires)` : '';
+    lines.push(`  ${badge} ${name}  ${D}${source}${occ}${RST}`);
+    if (g.pattern) {
+      lines.push(`    ${D}pattern: ${g.pattern}${RST}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function exploreGateFirings(options = {}) {
+  const { feedbackDir, limit = 20, json = false } = options;
+  const firings = loadGateFirings(feedbackDir).slice(0, limit);
+
+  if (json) {
+    const payload = firings.map(f => ({
+      id: f.id,
+      signal: f.signal,
+      context: f.context || '',
+      reason: f.reason || '',
+      timestamp: f.timestamp,
+      scope: 'local',
+      result: 'blocked',
+    }));
+    return { firings: payload, total: payload.length, scope: 'local' };
+  }
+
+  const lines = [];
+  lines.push('');
+  lines.push(`${BD}thumbgate explore firings${RST}  ${scopeBadge()}`);
+  lines.push('─'.repeat(60));
+
+  if (firings.length === 0) {
+    lines.push('  No gate firings recorded yet.');
+  }
+
+  for (const f of firings) {
+    const ts = relDate(f.timestamp);
+    lines.push(`  ${R}[BLOCKED]${RST} ${(f.context || f.reason || '').slice(0, 60)}`);
+    lines.push(`    ${D}${ts}  reason: ${f.reason || 'unknown'}${RST}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  exploreLessons,
+  exploreRules,
+  exploreGates,
+  exploreGateFirings,
+  loadLessons,
+  loadGates,
+  loadRules,
+  loadGateFirings,
+};