tribunal-kit 9.2.4 → 9.2.5

package/.agent/scripts/skill_evolution.js

@@ -1,997 +1,997 @@
-#!/usr/bin/env node
-/**
- * skill_evolution.js — Tribunal Kit Skill Evolution Forge
- * =========================================================
- * Analyzes the delta between what the AI proposed and what the developer
- * actually committed, then distills those decisions into evolving
- * project-specific SKILL idioms — WITHOUT sending full files to any LLM.
- *
- * Core Strategy: Semantic Delta Extraction
- *   1. Read the raw git diff of staged/recent changes
- *   2. Strip trivial noise (whitespace, comments, import renames)
- *   3. Score remaining lines for "Architectural Weight"
- *   4. Only high-weight deltas reach the LLM reflection prompt
- *   5. LLM returns structured YAML idiom entries (not prose)
- *   6. Idioms are merged into .agent/skills/project-idioms/SKILL.md
- *
- * Usage:
- *   node .agent/scripts/skill_evolution.js digest
- *   node .agent/scripts/skill_evolution.js digest --dry-run
- *   node .agent/scripts/skill_evolution.js show
- *   node .agent/scripts/skill_evolution.js reset
- *   node .agent/scripts/skill_evolution.js status
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const https = require('https');
-const { execSync } = require('child_process');
-const readline = require('readline');
-
-// ── Colours ──────────────────────────────────────────────────────────────────
-const { GREEN, YELLOW, CYAN, RED, BLUE, BOLD, DIM, RESET } = require('./_colors');
-
-// ── Shared Utilities ──────────────────────────────────────────────────────────
-const { findAgentDir } = require('./_utils');
-
-function getPaths(startDir = process.cwd()) {
-  const agentDir = findAgentDir(startDir);
-  const skillDir = path.join(agentDir, 'skills', 'project-idioms');
-  const historyDir = path.join(agentDir, 'history', 'skill-evolution');
-  return {
-    agentDir,
-    skillDir,
-    skillFile: path.join(skillDir, 'SKILL.md'),
-    historyDir,
-    logFile: path.join(historyDir, 'digest-log.json'),
-  };
-}
-
-// ── Architectural Weight Patterns ────────────────────────────────────────────
-const HIGH_WEIGHT_PATTERNS = [
-  /\bclass\b/,
-  /\binterface\b/,
-  /\btype\s+\w+\s*=/,
-  /\bextends\b/,
-  /\bimplements\b/,
-  /\bthrow\b/,
-  /\bcatch\b/,
-  /\btry\b/,
-  /\bprisma\.\w+\(/,
-  /\bsupabase\./,
-  /\bfetch\(/,
-  /\baxios\./,
-  /\bReturnType\b/,
-  /\bPromise</,
-  /\basync\s+function/,
-  /\bawait\b/,
-  /\bexport\s+(default\s+)?(class|function|const)/,
-  /\bmodule\.exports\b/,
-  /\bRouter\b|\bapp\.(get|post|put|delete|patch)\(/,
-  /\buse[A-Z]\w+\(/,
-  /\bcreateContext\(/,
-  /\bz\.object\(/,
-  /\bPrisma\b|\bdrizzle\b/,
-  /\benv\.\w+/,
-  /\bprocess\.env\./,
-];
-
-const NOISE_PATTERNS = [
-  /^\s*$/,
-  /^\s*(\/\/|#|\/\*).*$/,
-  /^\s*\*/,
-  /^\s*import\s+\{[^}]+\}\s+from\s+['"](?!\.)/,
-  /^\s*(console\.(log|warn|error)|print\()/,
-  /^\s*\w+\s*[:,]?\s*$/,
-];
-
-function architecturalWeight(line) {
-  const code = line.replace(/^[+-]/, '').trim();
-  for (const p of NOISE_PATTERNS) {
-    if (p.test(code)) return 0;
-  }
-  for (const p of HIGH_WEIGHT_PATTERNS) {
-    if (p.test(code)) return 2;
-  }
-  return 1;
-}
-
-// ── Levenshtein Semantic Deduplication ───────────────────────────────────────
-// FIX: Replaces over-aggressive substring matching (.includes) with normalised
-// edit-distance similarity. A new idiom must differ by >= 20% from all existing
-// ones to be accepted. Threshold 0.80 = 80% similar → considered a duplicate.
-
-function levenshtein(a, b) {
-  const m = a.length,
-    n = b.length;
-  // Allocate DP table with base cases pre-filled
-  const dp = Array.from({ length: m + 1 }, (_, i) =>
-    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
-  );
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] =
-        a[i - 1] === b[j - 1]
-          ? dp[i - 1][j - 1]
-          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-    }
-  }
-  return dp[m][n];
-}
-
-function normalizedSimilarity(a, b) {
-  if (!a.length && !b.length) return 1.0;
-  const maxLen = Math.max(a.length, b.length);
-  if (maxLen === 0) return 1.0;
-  return 1 - levenshtein(a, b) / maxLen;
-}
-
-/**
- * Returns true if newPattern is semantically similar to any existing idiom.
- * Uses Levenshtein normalised similarity with a configurable threshold.
- * @param {string}   newPattern
- * @param {object[]} existingIdioms - array of { pattern } objects
- * @param {number}   threshold      - 0.0–1.0 (default 0.80 = 80% similar = duplicate)
- */
-function isDuplicateIdiom(newPattern, existingIdioms, threshold = 0.8) {
-  const newLow = newPattern.toLowerCase();
-  return existingIdioms.some(ex => {
-    const exLow = (ex.pattern || '').toLowerCase();
-    return normalizedSimilarity(newLow, exLow) >= threshold;
-  });
-}
-
-function semanticDelta(diffText, minWeight = 2) {
-  const lines = diffText.split('\n');
-  const kept = [];
-  let currentHunkHasHigh = false;
-  let hunkLines = [];
-
-  for (const line of lines) {
-    if (line.startsWith('---') || line.startsWith('+++') || line.startsWith('diff --git')) {
-      kept.push(line);
-      continue;
-    }
-    if (line.startsWith('@@')) {
-      if (currentHunkHasHigh) kept.push(...hunkLines);
-      currentHunkHasHigh = false;
-      hunkLines = [line];
-      continue;
-    }
-    if (line.startsWith('+') || line.startsWith('-')) {
-      const w = architecturalWeight(line);
-      hunkLines.push(line);
-      if (w >= minWeight) currentHunkHasHigh = true;
-    } else {
-      hunkLines.push(line);
-    }
-  }
-  if (currentHunkHasHigh) kept.push(...hunkLines);
-
-  let result = kept.join('\n');
-  result = result.replace(/\n( ?\n){3,}/g, '\n\n');
-  return result.trim();
-}
-
-// ── Git helpers ────────────────────────────────────────────────────────────────
-function getGitDiff(mode = 'staged') {
-  try {
-    let cmd;
-    if (mode === 'staged') cmd = 'git diff --cached --unified=3';
-    else if (mode === 'head') cmd = 'git diff HEAD~1 HEAD --unified=3';
-    else cmd = 'git diff --unified=3';
-    return execSync(cmd, {
-      encoding: 'utf8',
-      timeout: 10000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-  } catch {
-    return '';
-  }
-}
-
-function countTokensEstimate(text) {
-  return Math.max(1, Math.floor(text.length / 4));
-}
-
-// ── Idiom management ──────────────────────────────────────────────────────────
-function loadExistingIdioms() {
-  const { skillFile } = getPaths();
-  if (!fs.existsSync(skillFile)) return [];
-  const content = fs.readFileSync(skillFile, 'utf8');
-  const idioms = [];
-  const pattern = /\|\s*(\d+)\s*\|\s*`([^`]+)`\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*([^|]+)\|/g;
-  let m;
-  while ((m = pattern.exec(content)) !== null) {
-    idioms.push({
-      id: parseInt(m[1], 10),
-      pattern: m[2].trim(),
-      reason: m[3].trim(),
-      domain: m[4].trim(),
-      since: m[5].trim(),
-    });
-  }
-  return idioms;
-}
-
-function nextIdiomId(idioms) {
-  if (!idioms.length) return 1;
-  return Math.max(...idioms.map(i => i.id)) + 1;
-}
-
-function renderSkillMd(idioms, digestCount) {
-  const now = new Date().toISOString().slice(0, 10);
-  const rows = idioms.map(
-    i => `| ${i.id} | \`${i.pattern}\` | ${i.reason} | ${i.domain} | ${i.since} |`,
-  );
-  const table = rows.length ? rows.join('\n') : '_No idioms recorded yet._';
-
-  return `---
-name: project-idioms
-description: >
-  Auto-evolved skill containing project-specific architectural idioms.
-  Generated by skill_evolution.js — do not edit manually. Commit this
-  file to share your Engineering Culture across the team.
-version: auto
-last-updated: ${now}
-digest-cycles: ${digestCount}
-pattern: generator
----
-
-# Project Idioms — Auto-Evolved Skill
-
-> **Authority Level: ABSOLUTE**
-> These idioms were extracted from the developer's own code decisions.
-> They override generic agent defaults. Every agent MUST respect them.
-
----
-
-## How Idioms Are Born
-
-1. Developer commits code that differs from the AI proposal.
-2. \`skill_evolution.js digest\` extracts architectural deltas only.
-3. A minimal LLM reflection prompt (< 500 tokens) identifies the "WHY."
-4. The idiom is recorded here with a stable pattern + reason pair.
-
----
-
-## Recorded Idioms
-
-| ID | Pattern | Why This Project Uses It | Domain | Since |
-|:---|:--------|:-------------------------|:-------|:------|
-${table}
-
----
-
-## Enforcement Rules for All Agents
-
-\`\`\`
-□ Before proposing code: scan this skill's idiom table
-□ If your proposal contradicts an idiom → flag it explicitly
-□ Never override an idiom silently — always ask the developer first
-□ When citing an idiom: "Per Project Idiom #N: [pattern] — [reason]"
-\`\`\`
-
----
-
-## Digest History
-
-Last digest: \`${now}\`
-Total cycles: \`${digestCount}\`
-
-Run \`node .agent/scripts/skill_evolution.js status\` to see the full log.
-`;
-}
-
-function generateReflectionPrompt(delta) {
-  return `You are analyzing a code delta from a developer who changed an AI-proposed solution.
-Your only job: identify the ARCHITECTURAL IDIOM this change reveals about their project.
-
-Rules:
-- Return ONLY a YAML list of idioms. No prose. No explanation outside YAML.
-- Each idiom: pattern (code signature), reason (1 sentence WHY), domain (backend/frontend/database/general)
-- Ignore whitespace, comment, import changes — only architectural choices
-- If no meaningful idiom can be extracted, return: "idioms: []"
-- Maximum 3 idioms per delta.
-
-Delta:
-\`\`\`
-${delta.slice(0, 1500)}
-\`\`\`
-
-Output format (YAML only):
-idioms:
-  - pattern: "<code pattern or convention>"
-    reason: "<why this project uses this pattern>"
-    domain: "<backend|frontend|database|security|performance|general>"
-`;
-}
-
-function parseLlmYamlResponse(response) {
-  const idioms = [];
-  let inIdioms = false;
-  let current = {};
-
-  for (const line of response.split('\n')) {
-    const stripped = line.trim();
-    if (stripped === 'idioms:') {
-      inIdioms = true;
-      continue;
-    }
-    if (!inIdioms) continue;
-    if (stripped.startsWith('- pattern:')) {
-      if (current.pattern) idioms.push(current);
-      current = {
-        pattern: stripped.split(':', 2)[1].trim().replace(/^"|"$/g, ''),
-      };
-    } else if (stripped.startsWith('reason:') && current.pattern) {
-      current.reason = stripped.split(':', 2)[1].trim().replace(/^"|"$/g, '');
-    } else if (stripped.startsWith('domain:') && current.pattern) {
-      current.domain = stripped.split(':', 2)[1].trim().replace(/^"|"$/g, '');
-    }
-  }
-  if (current.pattern) idioms.push(current);
-  return idioms;
-}
-
-// ── Log helpers ────────────────────────────────────────────────────────────────
-function loadLog() {
-  const { historyDir, logFile } = getPaths();
-  fs.mkdirSync(historyDir, { recursive: true });
-  if (fs.existsSync(logFile)) {
-    try {
-      return JSON.parse(fs.readFileSync(logFile, 'utf8'));
-    } catch {
-      /* fallthrough */
-    }
-  }
-  return { cycles: [], total_tokens_saved: 0, total_idioms: 0 };
-}
-
-function saveLog(log) {
-  const { historyDir, logFile } = getPaths();
-  fs.mkdirSync(historyDir, { recursive: true });
-  fs.writeFileSync(logFile, JSON.stringify(log, null, 2), 'utf8');
-}
-
-// ── Auto-LLM API Integration ─────────────────────────────────────────────────
-// GENERATE: Eliminates the manual copy-paste loop by auto-detecting an API key
-// and calling the LLM directly. Falls back to manual mode if no key is found.
-// Supported providers (checked in order): Anthropic → OpenAI → Gemini.
-
-function detectLlmProvider() {
-  if (process.env.ANTHROPIC_API_KEY)
-    return { provider: 'anthropic', key: process.env.ANTHROPIC_API_KEY };
-  if (process.env.OPENAI_API_KEY) return { provider: 'openai', key: process.env.OPENAI_API_KEY };
-  if (process.env.GEMINI_API_KEY) return { provider: 'gemini', key: process.env.GEMINI_API_KEY };
-  return null;
-}
-
-/**
- * Call an LLM API with the reflection prompt. Returns the raw text response.
- * Uses only built-in Node.js `https` — zero external dependencies.
- *
- * @param {string} prompt    - The reflection prompt to send
- * @param {string} provider  - 'anthropic' | 'openai' | 'gemini'
- * @param {string} apiKey    - The API key
- * @returns {Promise<string|null>} LLM response text or null on failure
- */
-async function callLlmApi(prompt, provider, apiKey) {
-  const timeout = 30000; // 30s max — skill evolution is non-blocking
-
-  function httpsPost(hostname, path, headers, body) {
-    return new Promise((resolve, reject) => {
-      const data = JSON.stringify(body);
-      const req = https.request(
-        {
-          method: 'POST',
-          hostname,
-          path,
-          headers: { ...headers, 'Content-Length': Buffer.byteLength(data) },
-        },
-        res => {
-          let raw = '';
-          res.on('data', c => {
-            raw += c;
-          });
-          res.on('end', () => resolve(raw));
-          res.on('error', reject);
-        },
-      );
-      req.on('error', reject);
-      req.setTimeout(timeout, () => {
-        req.destroy(new Error('LLM API timeout'));
-      });
-      req.write(data);
-      req.end();
-    });
-  }
-
-  try {
-    if (provider === 'anthropic') {
-      const raw = await httpsPost(
-        'api.anthropic.com',
-        '/v1/messages',
-        {
-          'Content-Type': 'application/json',
-          'x-api-key': apiKey,
-          'anthropic-version': '2023-06-01',
-        },
-        {
-          model: 'claude-3-haiku-20240307', // Fastest/cheapest — idiom extraction
-          max_tokens: 512,
-          messages: [{ role: 'user', content: prompt }],
-        },
-      );
-      const json = JSON.parse(raw);
-      return json?.content?.[0]?.text ?? null;
-    }
-
-    if (provider === 'openai') {
-      const raw = await httpsPost(
-        'api.openai.com',
-        '/v1/chat/completions',
-        {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${apiKey}`,
-        },
-        {
-          model: 'gpt-4o-mini', // Cheapest capable model for YAML extraction
-          max_tokens: 512,
-          messages: [{ role: 'user', content: prompt }],
-          temperature: 0.1,
-        },
-      );
-      const json = JSON.parse(raw);
-      return json?.choices?.[0]?.message?.content ?? null;
-    }
-
-    if (provider === 'gemini') {
-      const raw = await httpsPost(
-        'generativelanguage.googleapis.com',
-        `/v1beta/models/gemini-1.5-flash:generateContent?key=${apiKey}`,
-        { 'Content-Type': 'application/json' },
-        {
-          contents: [{ parts: [{ text: prompt }] }],
-          generationConfig: { maxOutputTokens: 512, temperature: 0.1 },
-        },
-      );
-      const json = JSON.parse(raw);
-      return json?.candidates?.[0]?.content?.parts?.[0]?.text ?? null;
-    }
-  } catch {
-    return null; // Network/parse failure — caller falls back to manual mode
-  }
-  return null;
-}
-
-// ── Commands ──────────────────────────────────────────────────────────────────
-// ── Strategy Filtering ────────────────────────────────────────────────────────
-function applyStrategyFilter(signals, strategy) {
-  if (strategy === 'repair-only') {
-    return signals.filter(s => s.type === 'log_error');
-  }
-  return signals;
-}
-
-// ── Log Reflection Prompt ─────────────────────────────────────────────────────
-function generateLogReflectionPrompt(delta) {
-  return `You are analyzing runtime log signals (errors, tracebacks, and warnings) from an AI agent's execution.
-Your job is to identify systemic coding issues and extract evolution assets:
-1. **Idioms (Genes)**: Coding rules/conventions to prevent the AI from generating this mistake again.
-2. **Cases (Capsules)**: Rejection precedents (offending code pattern and why it failed) to block reviewers from approving it.
-
-Rules:
-- Return ONLY a YAML structure containing 'idioms:' and 'cases:'. No markdown boxes, no conversational prose.
-- Maximum 3 idioms and 3 cases.
-- If an asset category is not applicable, leave it empty (e.g., 'idioms: []').
-
-Log Signals:
-\`\`\`
-${delta.slice(0, 1800)}
-\`\`\`
-
-Output format (YAML only):
-idioms:
-  - pattern: "<code convention or rule to avoid this error>"
-    reason: "<why it is needed based on the error>"
-    domain: "<backend|frontend|database|security|performance|general>"
-cases:
-  - pattern: "<offending code snippet or error-triggering pattern>"
-    reason: "<specific runtime error / traceback reason>"
-    domain: "<backend|frontend|database|security|performance|general>"
-    verdict: "REJECTED"
-`;
-}
-
-// ── Combined YAML Parser ──────────────────────────────────────────────────────
-function parseEvolutionYaml(response) {
-  const idioms = [];
-  const cases = [];
-  let currentSection = null; // 'idioms' | 'cases'
-  let current = null;
-
-  const lines = response.split('\n');
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === 'idioms:') {
-      if (current) {
-        if (currentSection === 'idioms') idioms.push(current);
-        if (currentSection === 'cases') cases.push(current);
-      }
-      currentSection = 'idioms';
-      current = null;
-      continue;
-    }
-    if (trimmed === 'cases:') {
-      if (current) {
-        if (currentSection === 'idioms') idioms.push(current);
-        if (currentSection === 'cases') cases.push(current);
-      }
-      currentSection = 'cases';
-      current = null;
-      continue;
-    }
-
-    if (
-      trimmed.startsWith('- pattern:') ||
-      (trimmed.startsWith('- ') && trimmed.includes('pattern:'))
-    ) {
-      if (current) {
-        if (currentSection === 'idioms') idioms.push(current);
-        if (currentSection === 'cases') cases.push(current);
-      }
-      let pat = '';
-      if (trimmed.startsWith('- pattern:')) {
-        pat = trimmed.substring('- pattern:'.length).trim();
-      } else {
-        pat = trimmed.split('pattern:', 2)[1].trim();
-      }
-      current = { pattern: pat.replace(/^['"]|['"]$/g, '') };
-    } else if (trimmed.startsWith('reason:') && current) {
-      current.reason = trimmed
-        .substring('reason:'.length)
-        .trim()
-        .replace(/^['"]|['"]$/g, '');
-    } else if (trimmed.startsWith('domain:') && current) {
-      current.domain = trimmed
-        .substring('domain:'.length)
-        .trim()
-        .replace(/^['"]|['"]$/g, '');
-    } else if (trimmed.startsWith('verdict:') && current) {
-      current.verdict = trimmed
-        .substring('verdict:'.length)
-        .trim()
-        .replace(/^['"]|['"]$/g, '');
-    }
-  }
-
-  if (current) {
-    if (currentSection === 'idioms') idioms.push(current);
-    if (currentSection === 'cases') cases.push(current);
-  }
-
-  return { idioms, cases };
-}
-
-// ── Commands ──────────────────────────────────────────────────────────────────
-async function cmdDigest(args) {
-  const dryRun = args.includes('--dry-run');
-  const diffMode = args.includes('--head') ? 'head' : 'staged';
-
-  const logArg = args.find(a => a.startsWith('--log='));
-  const logFile = logArg ? logArg.split('=').slice(1).join('=') : null;
-
-  const strategyArg = args.find(a => a.startsWith('--strategy='));
-  const strategy = strategyArg ? strategyArg.split('=').slice(1).join('=') : 'balanced';
-
-  console.log(`\n${BOLD}${CYAN}━━━ Skill Evolution — Digest Cycle ━━━━━━━━━━━━━━━━${RESET}`);
-  if (dryRun) console.log(`  ${YELLOW}DRY RUN — no files will be written${RESET}\n`);
-
-  let rawDiff = '';
-  let delta = '';
-  let rawTokens = 0;
-  let deltaTokens = 0;
-  let logSignals = [];
-  const isLogMode = !!logFile;
-
-  if (isLogMode) {
-    console.log(`  ${DIM}[1/5] Reading log file: ${logFile}...${RESET}`);
-    if (!fs.existsSync(logFile)) {
-      console.log(`  ${RED}✖ Log file not found: ${logFile}${RESET}\n`);
-      return;
-    }
-    const logText = fs.readFileSync(logFile, 'utf8');
-    rawTokens = countTokensEstimate(logText);
-
-    console.log(`  ${DIM}[2/5] Extracting signals from log (Signal Detector)...${RESET}`);
-    const { detectSignals } = require('./signal_detector');
-    const signals = detectSignals(logText);
-
-    if (signals.length === 0) {
-      console.log(`  ${GREEN}✔ No errors or performance signals found in logs.${RESET}`);
-      console.log(`  ${DIM}  No self-evolution reflection needed.${RESET}\n`);
-      return;
-    }
-
-    logSignals = applyStrategyFilter(signals, strategy);
-    if (logSignals.length === 0) {
-      console.log(`  ${YELLOW}⚠ Strategy filter [${strategy}] filtered out all signals.${RESET}\n`);
-      return;
-    }
-
-    console.log(
-      `  ${GREEN}✔ Filtered to ${logSignals.length} signal(s) using [${strategy}] strategy.${RESET}`,
-    );
-
-    delta = logSignals
-      .map(s => {
-        let chunk = `--- SIGNAL: ${s.type} ---\n`;
-        if (s.file) chunk += `File: ${s.file}${s.line ? `:${s.line}` : ''}\n`;
-        chunk += `Message: ${s.message}\n`;
-        chunk += `Context:\n${s.context}\n`;
-        return chunk;
-      })
-      .join('\n\n');
-
-    deltaTokens = countTokensEstimate(delta);
-  } else {
-    console.log(`  ${DIM}[1/5] Fetching git diff (${diffMode})...${RESET}`);
-    rawDiff = getGitDiff(diffMode);
-    if (!rawDiff.trim()) {
-      console.log(`  ${YELLOW}⚠ No diff found. Commit or stage changes first.${RESET}`);
-      console.log(`  ${DIM}Tip: Use --head to diff against the last commit.${RESET}\n`);
-      return;
-    }
-
-    rawTokens = countTokensEstimate(rawDiff);
-    console.log(`  ${DIM}   Raw diff: ~${rawTokens} tokens (${rawDiff.length} chars)${RESET}`);
-
-    console.log(`  ${DIM}[2/5] Extracting architectural delta (Semantic Filter)...${RESET}`);
-    delta = semanticDelta(rawDiff, 2);
-    if (!delta.trim()) {
-      console.log(`  ${GREEN}✔ Delta is 100% trivial (whitespace/comments/imports only).${RESET}`);
-      console.log(`  ${DIM}  No LLM call needed. Zero tokens consumed.${RESET}\n`);
-      return;
-    }
-
-    deltaTokens = countTokensEstimate(delta);
-  }
-
-  const savedTokens = Math.max(0, rawTokens - deltaTokens);
-  const savedPct = Math.floor((savedTokens / Math.max(rawTokens, 1)) * 100);
-  console.log(
-    `  ${GREEN}✔ Filtered to ~${deltaTokens} tokens  (${savedPct}% reduction, saved ~${savedTokens} tokens)${RESET}`,
-  );
-
-  console.log(`\n  ${BOLD}Architectural Delta Preview:${RESET}`);
-  const previewLines = delta.split('\n').slice(0, 20);
-  for (const line of previewLines) {
-    if (line.startsWith('+')) console.log(`    ${GREEN}${line}${RESET}`);
-    else if (line.startsWith('-')) console.log(`    ${RED}${line}${RESET}`);
-    else if (line.startsWith('@@')) console.log(`    ${BLUE}${line}${RESET}`);
-    else console.log(`    ${DIM}${line}${RESET}`);
-  }
-  if (delta.split('\n').length > 20)
-    console.log(`    ... (${delta.split('\n').length - 20} more lines)`);
-
-  if (dryRun) {
-    console.log(
-      `\n  ${YELLOW}[DRY RUN] Would send ${deltaTokens} tokens to LLM for reflection.${RESET}`,
-    );
-    console.log(`  ${DIM}Run without --dry-run to complete the digest.${RESET}\n`);
-    return;
-  }
-
-  // GENERATE: Auto-LLM call.
-  const reflectionPrompt = isLogMode
-    ? generateLogReflectionPrompt(delta)
-    : generateReflectionPrompt(delta);
-  let llmResponse = '';
-
-  let llmCreds = detectLlmProvider();
-  if (llmCreds) {
-    console.log(`  ${DIM}[3/5] LLM Reflection — auto-calling ${llmCreds.provider} API...${RESET}`);
-    const autoResponse = await callLlmApi(reflectionPrompt, llmCreds.provider, llmCreds.key);
-    if (autoResponse) {
-      llmResponse = autoResponse;
-      console.log(
-        `  ${GREEN}✔ Auto-response received (${llmCreds.provider}) — ${llmResponse.split('\n').length} lines${RESET}`,
-      );
-    } else {
-      console.log(`  ${YELLOW}⚠ API call failed — falling back to manual mode${RESET}`);
-      llmCreds = null;
-    }
-  }
-
-  if (!llmCreds || !llmResponse) {
-    // Manual fallback: copy-paste mode
-    console.log(
-      `\n  ${DIM}[3/5] LLM Reflection — copy the prompt below and paste the response${RESET}`,
-    );
-    console.log(
-      `  ${DIM}  Tip: Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY to automate this step.${RESET}`,
-    );
-    console.log(`\n  ${BOLD}${'─'.repeat(60)}${RESET}`);
-    console.log(reflectionPrompt);
-    console.log(`  ${BOLD}${'─'.repeat(60)}${RESET}`);
-    console.log(`\n  ${BOLD}Paste LLM response below (type END_RESPONSE when done):${RESET}`);
-
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    const responseLines = [];
-    await new Promise(resolve => {
-      const listener = line => {
-        if (line.trim() === 'END_RESPONSE') {
-          rl.removeListener('line', listener);
-          resolve();
-        } else responseLines.push(line);
-      };
-      rl.on('line', listener);
-    });
-    rl.close();
-    llmResponse = responseLines.join('\n');
-  }
-
-  console.log(`\n  ${DIM}[4/5] Parsing idioms/cases...${RESET}`);
-  let newIdioms = [];
-  let newCases = [];
-
-  if (isLogMode) {
-    const parsed = parseEvolutionYaml(llmResponse);
-    newIdioms = parsed.idioms;
-    newCases = parsed.cases;
-  } else {
-    newIdioms = parseLlmYamlResponse(llmResponse);
-  }
-
-  if (!newIdioms.length && !newCases.length) {
-    console.log(`  ${YELLOW}⚠ No idioms or cases extracted from LLM response.${RESET}`);
-    console.log(`\n`);
-    return;
-  }
-
-  if (newIdioms.length > 0) {
-    console.log(`  ${GREEN}✔ Extracted ${newIdioms.length} idiom(s)${RESET}`);
-    for (const idiom of newIdioms) {
-      console.log(`    ${CYAN}• ${idiom.pattern || '?'}${RESET}  — ${idiom.reason || ''}`);
-    }
-  }
-
-  if (newCases.length > 0) {
-    console.log(`  ${GREEN}✔ Extracted ${newCases.length} case precedent(s)${RESET}`);
-    for (const c of newCases) {
-      console.log(`    ${RED}• ${c.pattern || '?'}${RESET}  — ${c.reason || ''}`);
-    }
-  }
-
-  console.log(`\n  ${DIM}[5/5] Merging into project-idioms/SKILL.md...${RESET}`);
-  const existing = loadExistingIdioms();
-  const log = loadLog();
-  let nextId = nextIdiomId(existing);
-  const today = new Date().toISOString().slice(0, 10);
-  const merged = [...existing];
-  let added = 0;
-
-  for (const idiom of newIdioms) {
-    if (isDuplicateIdiom(idiom.pattern || '', existing)) {
-      console.log(`  ${DIM}  Skipped near-duplicate idiom: ${idiom.pattern}${RESET}`);
-      continue;
-    }
-    merged.push({
-      id: nextId,
-      pattern: idiom.pattern || '?',
-      reason: idiom.reason || 'No reason provided.',
-      domain: idiom.domain || 'general',
-      since: today,
-    });
-    nextId++;
-    added++;
-  }
-
-  if (added > 0) {
-    log.total_idioms = merged.length;
-    const skillMd = renderSkillMd(merged, (log.cycles || []).length + 1);
-    const { skillDir, skillFile } = getPaths();
-    fs.mkdirSync(skillDir, { recursive: true });
-    fs.writeFileSync(skillFile, skillMd, 'utf8');
-    console.log(`  ${GREEN}✔ ${added} new idiom(s) added to SKILL.md${RESET}`);
-  } else {
-    console.log(`  ${DIM}  No new unique idioms added to SKILL.md.${RESET}`);
-  }
-
-  // Record Case Precedents if present
-  if (newCases && newCases.length > 0) {
-    console.log(`\n  ${DIM}Merging into Case Law precedents...${RESET}`);
-    const caseLawManager = require('./case_law_manager');
-    const clIndex = caseLawManager.loadIndex();
-    let clNextId = clIndex.next_id;
-    let clAdded = 0;
-
-    for (const c of newCases) {
-      const diffText = c.pattern || '';
-      const reason = c.reason || '';
-      const domain = c.domain || 'general';
-      const verdict = c.verdict || 'REJECTED';
-      const fingerprint = caseLawManager.contentHash(diffText);
-
-      let isDup = false;
-      for (const existing of clIndex.cases) {
-        if (existing.fingerprint === fingerprint) {
-          isDup = true;
-          break;
-        }
-      }
-      if (isDup) {
-        console.log(`  ${DIM}  Skipped duplicate case: ${reason.slice(0, 50)}...${RESET}`);
-        continue;
-      }
-
-      const deltaCase = caseLawManager.semanticDelta(diffText);
-      const tags = caseLawManager.extractTags(diffText + ' ' + reason);
-      const caseRecord = {
-        id: clNextId,
-        fingerprint,
-        timestamp: new Date().toISOString().slice(0, 19),
-        domain,
-        verdict,
-        reason: reason.trim(),
-        pr_ref: 'auto-evolution',
-        reviewer: 'skill-evolution',
-        tags,
-        stack_version: null,
-        diff_raw: diffText.trim(),
-        diff_delta: deltaCase,
-        auto_recorded: true,
-      };
-
-      caseLawManager.saveCase(caseRecord);
-      clIndex.cases.push({
-        id: clNextId,
-        fingerprint,
-        domain,
-        verdict,
-        tags,
-        timestamp: caseRecord.timestamp,
-        reason_summary: reason.trim().slice(0, 120),
-        stack_version: null,
-      });
-      clNextId++;
-      clAdded++;
-    }
-
-    if (clAdded > 0) {
-      clIndex.next_id = clNextId;
-      caseLawManager.saveIndex(clIndex);
-      console.log(`  ${GREEN}✔ ${clAdded} new Case Law precedent(s) recorded.${RESET}`);
-    } else {
-      console.log(`  ${DIM}  No new unique Case Law precedents recorded.${RESET}`);
-    }
-  }
-
-  log.cycles = log.cycles || [];
-  log.cycles.push({
-    timestamp: new Date().toISOString().slice(0, 19),
-    raw_tokens: rawTokens,
-    delta_tokens: deltaTokens,
-    tokens_saved: savedTokens,
-    idioms_added: added,
-  });
-  log.total_tokens_saved = (log.total_tokens_saved || 0) + savedTokens;
-  saveLog(log);
-
-  console.log(`\n  ${GREEN}✔ Learn cycle complete.${RESET}`);
-  console.log(`  ${DIM}   Total idioms: ${merged.length}${RESET}`);
-  console.log(`  ${DIM}   Lifetime tokens saved: ${log.total_tokens_saved}${RESET}\n`);
-}
-
-function cmdShow() {
-  const { skillFile } = getPaths();
-  if (!fs.existsSync(skillFile)) {
-    console.log(`${YELLOW}No project-idioms skill found. Run 'digest' first.${RESET}`);
-    return;
-  }
-  console.log(fs.readFileSync(skillFile, 'utf8'));
-}
-
-function cmdReset() {
-  const { skillFile, logFile } = getPaths();
-  if (fs.existsSync(skillFile)) {
-    fs.unlinkSync(skillFile);
-    console.log(`${GREEN}✔ project-idioms/SKILL.md deleted.${RESET}`);
-  }
-  if (fs.existsSync(logFile)) {
-    fs.unlinkSync(logFile);
-    console.log(`${GREEN}✔ Digest log cleared.${RESET}`);
-  }
-  console.log(`${DIM}Run 'digest' to start a fresh evolution cycle.${RESET}`);
-}
-
-function cmdStatus() {
-  const log = loadLog();
-  const cycles = log.cycles || [];
-  const totalSaved = log.total_tokens_saved || 0;
-  const totalIdioms = log.total_idioms || 0;
-  const { skillFile } = getPaths();
-  const idiomsExist = fs.existsSync(skillFile);
-
-  console.log(`\n${BOLD}${CYAN}━━━ Skill Evolution Status ━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
-  console.log(`  Digest cycles    : ${BOLD}${cycles.length}${RESET}`);
-  console.log(`  Total idioms     : ${BOLD}${totalIdioms}${RESET}`);
-  console.log(
-    `  Tokens saved     : ${GREEN}${totalSaved.toLocaleString()} tokens${RESET}  (≈ $${((totalSaved / 1_000_000) * 3).toFixed(4)} at $3/M)`,
-  );
-  console.log(`  SKILL.md exists  : ${idiomsExist ? '✔' : '✗'}`);
-
-  if (cycles.length) {
-    console.log(`\n  ${BOLD}Last 5 digest cycles:${RESET}`);
-    for (const cycle of cycles.slice(-5).reverse()) {
-      const ts = (cycle.timestamp || '?').slice(0, 16);
-      const deltaT = cycle.delta_tokens || 0;
-      const saved = cycle.tokens_saved || 0;
-      const addedCount = cycle.idioms_added || 0;
-      const pct = Math.floor((saved / Math.max(cycle.raw_tokens || 1, 1)) * 100);
-      console.log(
-        `    ${DIM}${ts}${RESET}  delta=${deltaT}tok  saved=${saved}tok (${pct}%)  idioms+=${addedCount}`,
-      );
-    }
-  }
-  console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`);
-}
-
-// ── Main ──────────────────────────────────────────────────────────────────────
-const COMMANDS = {
-  digest: cmdDigest,
-  show: cmdShow,
-  reset: cmdReset,
-  status: cmdStatus,
-};
-
-async function main() {
-  const argv = process.argv.slice(2);
-  if (!argv.length || ['-h', '--help', 'help'].includes(argv[0])) {
-    console.log(`
-${BOLD}skill_evolution.js${RESET} — Tribunal Skill Evolution Forge
-
-${BOLD}Commands:${RESET}
-  digest [--dry-run] [--head]   Analyze latest git diff and evolve SKILL.md
-                                  --dry-run  : preview without writing
-                                  --head     : diff last commit instead of staged
-  show                           Print current project-idioms/SKILL.md
-  status                         Show digest history and token savings
-  reset                          Clear all idioms and start fresh
-
-${BOLD}Token Budget:${RESET}
-  Raw diff -> Semantic Filter -> Only architectural lines -> LLM
-  Typical savings: 70–90% of tokens. Most trivial commits = 0 tokens.
-`);
-    return;
-  }
-
-  const cmd = argv[0];
-  const rest = argv.slice(1);
-  if (!COMMANDS[cmd]) {
-    console.log(`${RED}✖ Unknown command: '${cmd}'${RESET}`);
-    process.exit(1);
-  }
-  await COMMANDS[cmd](rest);
-}
-
-module.exports = {
-  semanticDelta,
-  architecturalWeight,
-  parseLlmYamlResponse,
-  loadExistingIdioms,
-  getPaths,
-};
-
-if (require.main === module) {
-  main().catch(err => {
-    console.error(err);
-    process.exit(1);
-  });
-}
+#!/usr/bin/env node
+/**
+ * skill_evolution.js — Tribunal Kit Skill Evolution Forge
+ * =========================================================
+ * Analyzes the delta between what the AI proposed and what the developer
+ * actually committed, then distills those decisions into evolving
+ * project-specific SKILL idioms — WITHOUT sending full files to any LLM.
+ *
+ * Core Strategy: Semantic Delta Extraction
+ *   1. Read the raw git diff of staged/recent changes
+ *   2. Strip trivial noise (whitespace, comments, import renames)
+ *   3. Score remaining lines for "Architectural Weight"
+ *   4. Only high-weight deltas reach the LLM reflection prompt
+ *   5. LLM returns structured YAML idiom entries (not prose)
+ *   6. Idioms are merged into .agent/skills/project-idioms/SKILL.md
+ *
+ * Usage:
+ *   node .agent/scripts/skill_evolution.js digest
+ *   node .agent/scripts/skill_evolution.js digest --dry-run
+ *   node .agent/scripts/skill_evolution.js show
+ *   node .agent/scripts/skill_evolution.js reset
+ *   node .agent/scripts/skill_evolution.js status
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execFileSync } = require('child_process');
+const readline = require('readline');
+
+// ── Colours ──────────────────────────────────────────────────────────────────
+const { GREEN, YELLOW, CYAN, RED, BLUE, BOLD, DIM, RESET } = require('./_colors');
+
+// ── Shared Utilities ──────────────────────────────────────────────────────────
+const { findAgentDir } = require('./_utils');
+
+function getPaths(startDir = process.cwd()) {
+  const agentDir = findAgentDir(startDir);
+  const skillDir = path.join(agentDir, 'skills', 'project-idioms');
+  const historyDir = path.join(agentDir, 'history', 'skill-evolution');
+  return {
+    agentDir,
+    skillDir,
+    skillFile: path.join(skillDir, 'SKILL.md'),
+    historyDir,
+    logFile: path.join(historyDir, 'digest-log.json'),
+  };
+}
+
+// ── Architectural Weight Patterns ────────────────────────────────────────────
+const HIGH_WEIGHT_PATTERNS = [
+  /\bclass\b/,
+  /\binterface\b/,
+  /\btype\s+\w+\s*=/,
+  /\bextends\b/,
+  /\bimplements\b/,
+  /\bthrow\b/,
+  /\bcatch\b/,
+  /\btry\b/,
+  /\bprisma\.\w+\(/,
+  /\bsupabase\./,
+  /\bfetch\(/,
+  /\baxios\./,
+  /\bReturnType\b/,
+  /\bPromise</,
+  /\basync\s+function/,
+  /\bawait\b/,
+  /\bexport\s+(default\s+)?(class|function|const)/,
+  /\bmodule\.exports\b/,
+  /\bRouter\b|\bapp\.(get|post|put|delete|patch)\(/,
+  /\buse[A-Z]\w+\(/,
+  /\bcreateContext\(/,
+  /\bz\.object\(/,
+  /\bPrisma\b|\bdrizzle\b/,
+  /\benv\.\w+/,
+  /\bprocess\.env\./,
+];
+
+const NOISE_PATTERNS = [
+  /^\s*$/,
+  /^\s*(\/\/|#|\/\*).*$/,
+  /^\s*\*/,
+  /^\s*import\s+\{[^}]+\}\s+from\s+['"](?!\.)/,
+  /^\s*(console\.(log|warn|error)|print\()/,
+  /^\s*\w+\s*[:,]?\s*$/,
+];
+
+function architecturalWeight(line) {
+  const code = line.replace(/^[+-]/, '').trim();
+  for (const p of NOISE_PATTERNS) {
+    if (p.test(code)) return 0;
+  }
+  for (const p of HIGH_WEIGHT_PATTERNS) {
+    if (p.test(code)) return 2;
+  }
+  return 1;
+}
+
+// ── Levenshtein Semantic Deduplication ───────────────────────────────────────
+// FIX: Replaces over-aggressive substring matching (.includes) with normalised
+// edit-distance similarity. A new idiom must differ by >= 20% from all existing
+// ones to be accepted. Threshold 0.80 = 80% similar → considered a duplicate.
+
+function levenshtein(a, b) {
+  const m = a.length,
+    n = b.length;
+  // Allocate DP table with base cases pre-filled
+  const dp = Array.from({ length: m + 1 }, (_, i) =>
+    Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function normalizedSimilarity(a, b) {
+  if (!a.length && !b.length) return 1.0;
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1.0;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+
+/**
+ * Returns true if newPattern is semantically similar to any existing idiom.
+ * Uses Levenshtein normalised similarity with a configurable threshold.
+ * @param {string}   newPattern
+ * @param {object[]} existingIdioms - array of { pattern } objects
+ * @param {number}   threshold      - 0.0–1.0 (default 0.80 = 80% similar = duplicate)
+ */
+function isDuplicateIdiom(newPattern, existingIdioms, threshold = 0.8) {
+  const newLow = newPattern.toLowerCase();
+  return existingIdioms.some(ex => {
+    const exLow = (ex.pattern || '').toLowerCase();
+    return normalizedSimilarity(newLow, exLow) >= threshold;
+  });
+}
+
+function semanticDelta(diffText, minWeight = 2) {
+  const lines = diffText.split('\n');
+  const kept = [];
+  let currentHunkHasHigh = false;
+  let hunkLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith('---') || line.startsWith('+++') || line.startsWith('diff --git')) {
+      kept.push(line);
+      continue;
+    }
+    if (line.startsWith('@@')) {
+      if (currentHunkHasHigh) kept.push(...hunkLines);
+      currentHunkHasHigh = false;
+      hunkLines = [line];
+      continue;
+    }
+    if (line.startsWith('+') || line.startsWith('-')) {
+      const w = architecturalWeight(line);
+      hunkLines.push(line);
+      if (w >= minWeight) currentHunkHasHigh = true;
+    } else {
+      hunkLines.push(line);
+    }
+  }
+  if (currentHunkHasHigh) kept.push(...hunkLines);
+
+  let result = kept.join('\n');
+  result = result.replace(/\n( ?\n){3,}/g, '\n\n');
+  return result.trim();
+}
+
+// ── Git helpers ────────────────────────────────────────────────────────────────
+function getGitDiff(mode = 'staged') {
+  try {
+    let args = [];
+    if (mode === 'staged') args = ['diff', '--cached', '--unified=3'];
+    else if (mode === 'head') args = ['diff', 'HEAD~1', 'HEAD', '--unified=3'];
+    else args = ['diff', '--unified=3'];
+    return execFileSync('git', args, {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    return '';
+  }
+}
+
+function countTokensEstimate(text) {
+  return Math.max(1, Math.floor(text.length / 4));
+}
+
+// ── Idiom management ──────────────────────────────────────────────────────────
+function loadExistingIdioms() {
+  const { skillFile } = getPaths();
+  if (!fs.existsSync(skillFile)) return [];
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const idioms = [];
+  const pattern = /\|\s*(\d+)\s*\|\s*`([^`]+)`\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*([^|]+)\|/g;
+  let m;
+  while ((m = pattern.exec(content)) !== null) {
+    idioms.push({
+      id: parseInt(m[1], 10),
+      pattern: m[2].trim(),
+      reason: m[3].trim(),
+      domain: m[4].trim(),
+      since: m[5].trim(),
+    });
+  }
+  return idioms;
+}
+
+function nextIdiomId(idioms) {
+  if (!idioms.length) return 1;
+  return Math.max(...idioms.map(i => i.id)) + 1;
+}
+
+function renderSkillMd(idioms, digestCount) {
+  const now = new Date().toISOString().slice(0, 10);
+  const rows = idioms.map(
+    i => `| ${i.id} | \`${i.pattern}\` | ${i.reason} | ${i.domain} | ${i.since} |`,
+  );
+  const table = rows.length ? rows.join('\n') : '_No idioms recorded yet._';
+
+  return `---
+name: project-idioms
+description: >
+  Auto-evolved skill containing project-specific architectural idioms.
+  Generated by skill_evolution.js — do not edit manually. Commit this
+  file to share your Engineering Culture across the team.
+version: auto
+last-updated: ${now}
+digest-cycles: ${digestCount}
+pattern: generator
+---
+
+# Project Idioms — Auto-Evolved Skill
+
+> **Authority Level: ABSOLUTE**
+> These idioms were extracted from the developer's own code decisions.
+> They override generic agent defaults. Every agent MUST respect them.
+
+---
+
+## How Idioms Are Born
+
+1. Developer commits code that differs from the AI proposal.
+2. \`skill_evolution.js digest\` extracts architectural deltas only.
+3. A minimal LLM reflection prompt (< 500 tokens) identifies the "WHY."
+4. The idiom is recorded here with a stable pattern + reason pair.
+
+---
+
+## Recorded Idioms
+
+| ID | Pattern | Why This Project Uses It | Domain | Since |
+|:---|:--------|:-------------------------|:-------|:------|
+${table}
+
+---
+
+## Enforcement Rules for All Agents
+
+\`\`\`
+□ Before proposing code: scan this skill's idiom table
+□ If your proposal contradicts an idiom → flag it explicitly
+□ Never override an idiom silently — always ask the developer first
+□ When citing an idiom: "Per Project Idiom #N: [pattern] — [reason]"
+\`\`\`
+
+---
+
+## Digest History
+
+Last digest: \`${now}\`
+Total cycles: \`${digestCount}\`
+
+Run \`node .agent/scripts/skill_evolution.js status\` to see the full log.
+`;
+}
+
+function generateReflectionPrompt(delta) {
+  return `You are analyzing a code delta from a developer who changed an AI-proposed solution.
+Your only job: identify the ARCHITECTURAL IDIOM this change reveals about their project.
+
+Rules:
+- Return ONLY a YAML list of idioms. No prose. No explanation outside YAML.
+- Each idiom: pattern (code signature), reason (1 sentence WHY), domain (backend/frontend/database/general)
+- Ignore whitespace, comment, import changes — only architectural choices
+- If no meaningful idiom can be extracted, return: "idioms: []"
+- Maximum 3 idioms per delta.
+
+Delta:
+\`\`\`
+${delta.slice(0, 1500)}
+\`\`\`
+
+Output format (YAML only):
+idioms:
+  - pattern: "<code pattern or convention>"
+    reason: "<why this project uses this pattern>"
+    domain: "<backend|frontend|database|security|performance|general>"
+`;
+}
+
+function parseLlmYamlResponse(response) {
+  const idioms = [];
+  let inIdioms = false;
+  let current = {};
+
+  for (const line of response.split('\n')) {
+    const stripped = line.trim();
+    if (stripped === 'idioms:') {
+      inIdioms = true;
+      continue;
+    }
+    if (!inIdioms) continue;
+    if (stripped.startsWith('- pattern:')) {
+      if (current.pattern) idioms.push(current);
+      current = {
+        pattern: stripped.split(':', 2)[1].trim().replace(/^"|"$/g, ''),
+      };
+    } else if (stripped.startsWith('reason:') && current.pattern) {
+      current.reason = stripped.split(':', 2)[1].trim().replace(/^"|"$/g, '');
+    } else if (stripped.startsWith('domain:') && current.pattern) {
+      current.domain = stripped.split(':', 2)[1].trim().replace(/^"|"$/g, '');
+    }
+  }
+  if (current.pattern) idioms.push(current);
+  return idioms;
+}
+
+// ── Log helpers ────────────────────────────────────────────────────────────────
+function loadLog() {
+  const { historyDir, logFile } = getPaths();
+  fs.mkdirSync(historyDir, { recursive: true });
+  if (fs.existsSync(logFile)) {
+    try {
+      return JSON.parse(fs.readFileSync(logFile, 'utf8'));
+    } catch {
+      /* fallthrough */
+    }
+  }
+  return { cycles: [], total_tokens_saved: 0, total_idioms: 0 };
+}
+
+function saveLog(log) {
+  const { historyDir, logFile } = getPaths();
+  fs.mkdirSync(historyDir, { recursive: true });
+  fs.writeFileSync(logFile, JSON.stringify(log, null, 2), 'utf8');
+}
+
+// ── Auto-LLM API Integration ─────────────────────────────────────────────────
+// GENERATE: Eliminates the manual copy-paste loop by auto-detecting an API key
+// and calling the LLM directly. Falls back to manual mode if no key is found.
+// Supported providers (checked in order): Anthropic → OpenAI → Gemini.
+
+function detectLlmProvider() {
+  if (process.env.ANTHROPIC_API_KEY)
+    return { provider: 'anthropic', key: process.env.ANTHROPIC_API_KEY };
+  if (process.env.OPENAI_API_KEY) return { provider: 'openai', key: process.env.OPENAI_API_KEY };
+  if (process.env.GEMINI_API_KEY) return { provider: 'gemini', key: process.env.GEMINI_API_KEY };
+  return null;
+}
+
+/**
+ * Call an LLM API with the reflection prompt. Returns the raw text response.
+ * Uses only built-in Node.js `https` — zero external dependencies.
+ *
+ * @param {string} prompt    - The reflection prompt to send
+ * @param {string} provider  - 'anthropic' | 'openai' | 'gemini'
+ * @param {string} apiKey    - The API key
+ * @returns {Promise<string|null>} LLM response text or null on failure
+ */
+async function callLlmApi(prompt, provider, apiKey) {
+  const timeout = 30000; // 30s max — skill evolution is non-blocking
+
+  function httpsPost(hostname, path, headers, body) {
+    return new Promise((resolve, reject) => {
+      const data = JSON.stringify(body);
+      const req = https.request(
+        {
+          method: 'POST',
+          hostname,
+          path,
+          headers: { ...headers, 'Content-Length': Buffer.byteLength(data) },
+        },
+        res => {
+          let raw = '';
+          res.on('data', c => {
+            raw += c;
+          });
+          res.on('end', () => resolve(raw));
+          res.on('error', reject);
+        },
+      );
+      req.on('error', reject);
+      req.setTimeout(timeout, () => {
+        req.destroy(new Error('LLM API timeout'));
+      });
+      req.write(data);
+      req.end();
+    });
+  }
+
+  try {
+    if (provider === 'anthropic') {
+      const raw = await httpsPost(
+        'api.anthropic.com',
+        '/v1/messages',
+        {
+          'Content-Type': 'application/json',
+          'x-api-key': apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        {
+          model: 'claude-3-haiku-20240307', // Fastest/cheapest — idiom extraction
+          max_tokens: 512,
+          messages: [{ role: 'user', content: prompt }],
+        },
+      );
+      const json = JSON.parse(raw);
+      return json?.content?.[0]?.text ?? null;
+    }
+
+    if (provider === 'openai') {
+      const raw = await httpsPost(
+        'api.openai.com',
+        '/v1/chat/completions',
+        {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        {
+          model: 'gpt-4o-mini', // Cheapest capable model for YAML extraction
+          max_tokens: 512,
+          messages: [{ role: 'user', content: prompt }],
+          temperature: 0.1,
+        },
+      );
+      const json = JSON.parse(raw);
+      return json?.choices?.[0]?.message?.content ?? null;
+    }
+
+    if (provider === 'gemini') {
+      const raw = await httpsPost(
+        'generativelanguage.googleapis.com',
+        `/v1beta/models/gemini-1.5-flash:generateContent?key=${apiKey}`,
+        { 'Content-Type': 'application/json' },
+        {
+          contents: [{ parts: [{ text: prompt }] }],
+          generationConfig: { maxOutputTokens: 512, temperature: 0.1 },
+        },
+      );
+      const json = JSON.parse(raw);
+      return json?.candidates?.[0]?.content?.parts?.[0]?.text ?? null;
+    }
+  } catch {
+    return null; // Network/parse failure — caller falls back to manual mode
+  }
+  return null;
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+// ── Strategy Filtering ────────────────────────────────────────────────────────
+function applyStrategyFilter(signals, strategy) {
+  if (strategy === 'repair-only') {
+    return signals.filter(s => s.type === 'log_error');
+  }
+  return signals;
+}
+
+// ── Log Reflection Prompt ─────────────────────────────────────────────────────
+function generateLogReflectionPrompt(delta) {
+  return `You are analyzing runtime log signals (errors, tracebacks, and warnings) from an AI agent's execution.
+Your job is to identify systemic coding issues and extract evolution assets:
+1. **Idioms (Genes)**: Coding rules/conventions to prevent the AI from generating this mistake again.
+2. **Cases (Capsules)**: Rejection precedents (offending code pattern and why it failed) to block reviewers from approving it.
+
+Rules:
+- Return ONLY a YAML structure containing 'idioms:' and 'cases:'. No markdown boxes, no conversational prose.
+- Maximum 3 idioms and 3 cases.
+- If an asset category is not applicable, leave it empty (e.g., 'idioms: []').
+
+Log Signals:
+\`\`\`
+${delta.slice(0, 1800)}
+\`\`\`
+
+Output format (YAML only):
+idioms:
+  - pattern: "<code convention or rule to avoid this error>"
+    reason: "<why it is needed based on the error>"
+    domain: "<backend|frontend|database|security|performance|general>"
+cases:
+  - pattern: "<offending code snippet or error-triggering pattern>"
+    reason: "<specific runtime error / traceback reason>"
+    domain: "<backend|frontend|database|security|performance|general>"
+    verdict: "REJECTED"
+`;
+}
+
+// ── Combined YAML Parser ──────────────────────────────────────────────────────
+function parseEvolutionYaml(response) {
+  const idioms = [];
+  const cases = [];
+  let currentSection = null; // 'idioms' | 'cases'
+  let current = null;
+
+  const lines = response.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === 'idioms:') {
+      if (current) {
+        if (currentSection === 'idioms') idioms.push(current);
+        if (currentSection === 'cases') cases.push(current);
+      }
+      currentSection = 'idioms';
+      current = null;
+      continue;
+    }
+    if (trimmed === 'cases:') {
+      if (current) {
+        if (currentSection === 'idioms') idioms.push(current);
+        if (currentSection === 'cases') cases.push(current);
+      }
+      currentSection = 'cases';
+      current = null;
+      continue;
+    }
+
+    if (
+      trimmed.startsWith('- pattern:') ||
+      (trimmed.startsWith('- ') && trimmed.includes('pattern:'))
+    ) {
+      if (current) {
+        if (currentSection === 'idioms') idioms.push(current);
+        if (currentSection === 'cases') cases.push(current);
+      }
+      let pat = '';
+      if (trimmed.startsWith('- pattern:')) {
+        pat = trimmed.substring('- pattern:'.length).trim();
+      } else {
+        pat = trimmed.split('pattern:', 2)[1].trim();
+      }
+      current = { pattern: pat.replace(/^['"]|['"]$/g, '') };
+    } else if (trimmed.startsWith('reason:') && current) {
+      current.reason = trimmed
+        .substring('reason:'.length)
+        .trim()
+        .replace(/^['"]|['"]$/g, '');
+    } else if (trimmed.startsWith('domain:') && current) {
+      current.domain = trimmed
+        .substring('domain:'.length)
+        .trim()
+        .replace(/^['"]|['"]$/g, '');
+    } else if (trimmed.startsWith('verdict:') && current) {
+      current.verdict = trimmed
+        .substring('verdict:'.length)
+        .trim()
+        .replace(/^['"]|['"]$/g, '');
+    }
+  }
+
+  if (current) {
+    if (currentSection === 'idioms') idioms.push(current);
+    if (currentSection === 'cases') cases.push(current);
+  }
+
+  return { idioms, cases };
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+async function cmdDigest(args) {
+  const dryRun = args.includes('--dry-run');
+  const diffMode = args.includes('--head') ? 'head' : 'staged';
+
+  const logArg = args.find(a => a.startsWith('--log='));
+  const logFile = logArg ? logArg.split('=').slice(1).join('=') : null;
+
+  const strategyArg = args.find(a => a.startsWith('--strategy='));
+  const strategy = strategyArg ? strategyArg.split('=').slice(1).join('=') : 'balanced';
+
+  console.log(`\n${BOLD}${CYAN}━━━ Skill Evolution — Digest Cycle ━━━━━━━━━━━━━━━━${RESET}`);
+  if (dryRun) console.log(`  ${YELLOW}DRY RUN — no files will be written${RESET}\n`);
+
+  let rawDiff = '';
+  let delta = '';
+  let rawTokens = 0;
+  let deltaTokens = 0;
+  let logSignals = [];
+  const isLogMode = !!logFile;
+
+  if (isLogMode) {
+    console.log(`  ${DIM}[1/5] Reading log file: ${logFile}...${RESET}`);
+    if (!fs.existsSync(logFile)) {
+      console.log(`  ${RED}✖ Log file not found: ${logFile}${RESET}\n`);
+      return;
+    }
+    const logText = fs.readFileSync(logFile, 'utf8');
+    rawTokens = countTokensEstimate(logText);
+
+    console.log(`  ${DIM}[2/5] Extracting signals from log (Signal Detector)...${RESET}`);
+    const { detectSignals } = require('./signal_detector');
+    const signals = detectSignals(logText);
+
+    if (signals.length === 0) {
+      console.log(`  ${GREEN}✔ No errors or performance signals found in logs.${RESET}`);
+      console.log(`  ${DIM}  No self-evolution reflection needed.${RESET}\n`);
+      return;
+    }
+
+    logSignals = applyStrategyFilter(signals, strategy);
+    if (logSignals.length === 0) {
+      console.log(`  ${YELLOW}⚠ Strategy filter [${strategy}] filtered out all signals.${RESET}\n`);
+      return;
+    }
+
+    console.log(
+      `  ${GREEN}✔ Filtered to ${logSignals.length} signal(s) using [${strategy}] strategy.${RESET}`,
+    );
+
+    delta = logSignals
+      .map(s => {
+        let chunk = `--- SIGNAL: ${s.type} ---\n`;
+        if (s.file) chunk += `File: ${s.file}${s.line ? `:${s.line}` : ''}\n`;
+        chunk += `Message: ${s.message}\n`;
+        chunk += `Context:\n${s.context}\n`;
+        return chunk;
+      })
+      .join('\n\n');
+
+    deltaTokens = countTokensEstimate(delta);
+  } else {
+    console.log(`  ${DIM}[1/5] Fetching git diff (${diffMode})...${RESET}`);
+    rawDiff = getGitDiff(diffMode);
+    if (!rawDiff.trim()) {
+      console.log(`  ${YELLOW}⚠ No diff found. Commit or stage changes first.${RESET}`);
+      console.log(`  ${DIM}Tip: Use --head to diff against the last commit.${RESET}\n`);
+      return;
+    }
+
+    rawTokens = countTokensEstimate(rawDiff);
+    console.log(`  ${DIM}   Raw diff: ~${rawTokens} tokens (${rawDiff.length} chars)${RESET}`);
+
+    console.log(`  ${DIM}[2/5] Extracting architectural delta (Semantic Filter)...${RESET}`);
+    delta = semanticDelta(rawDiff, 2);
+    if (!delta.trim()) {
+      console.log(`  ${GREEN}✔ Delta is 100% trivial (whitespace/comments/imports only).${RESET}`);
+      console.log(`  ${DIM}  No LLM call needed. Zero tokens consumed.${RESET}\n`);
+      return;
+    }
+
+    deltaTokens = countTokensEstimate(delta);
+  }
+
+  const savedTokens = Math.max(0, rawTokens - deltaTokens);
+  const savedPct = Math.floor((savedTokens / Math.max(rawTokens, 1)) * 100);
+  console.log(
+    `  ${GREEN}✔ Filtered to ~${deltaTokens} tokens  (${savedPct}% reduction, saved ~${savedTokens} tokens)${RESET}`,
+  );
+
+  console.log(`\n  ${BOLD}Architectural Delta Preview:${RESET}`);
+  const previewLines = delta.split('\n').slice(0, 20);
+  for (const line of previewLines) {
+    if (line.startsWith('+')) console.log(`    ${GREEN}${line}${RESET}`);
+    else if (line.startsWith('-')) console.log(`    ${RED}${line}${RESET}`);
+    else if (line.startsWith('@@')) console.log(`    ${BLUE}${line}${RESET}`);
+    else console.log(`    ${DIM}${line}${RESET}`);
+  }
+  if (delta.split('\n').length > 20)
+    console.log(`    ... (${delta.split('\n').length - 20} more lines)`);
+
+  if (dryRun) {
+    console.log(
+      `\n  ${YELLOW}[DRY RUN] Would send ${deltaTokens} tokens to LLM for reflection.${RESET}`,
+    );
+    console.log(`  ${DIM}Run without --dry-run to complete the digest.${RESET}\n`);
+    return;
+  }
+
+  // GENERATE: Auto-LLM call.
+  const reflectionPrompt = isLogMode
+    ? generateLogReflectionPrompt(delta)
+    : generateReflectionPrompt(delta);
+  let llmResponse = '';
+
+  let llmCreds = detectLlmProvider();
+  if (llmCreds) {
+    console.log(`  ${DIM}[3/5] LLM Reflection — auto-calling ${llmCreds.provider} API...${RESET}`);
+    const autoResponse = await callLlmApi(reflectionPrompt, llmCreds.provider, llmCreds.key);
+    if (autoResponse) {
+      llmResponse = autoResponse;
+      console.log(
+        `  ${GREEN}✔ Auto-response received (${llmCreds.provider}) — ${llmResponse.split('\n').length} lines${RESET}`,
+      );
+    } else {
+      console.log(`  ${YELLOW}⚠ API call failed — falling back to manual mode${RESET}`);
+      llmCreds = null;
+    }
+  }
+
+  if (!llmCreds || !llmResponse) {
+    // Manual fallback: copy-paste mode
+    console.log(
+      `\n  ${DIM}[3/5] LLM Reflection — copy the prompt below and paste the response${RESET}`,
+    );
+    console.log(
+      `  ${DIM}  Tip: Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY to automate this step.${RESET}`,
+    );
+    console.log(`\n  ${BOLD}${'─'.repeat(60)}${RESET}`);
+    console.log(reflectionPrompt);
+    console.log(`  ${BOLD}${'─'.repeat(60)}${RESET}`);
+    console.log(`\n  ${BOLD}Paste LLM response below (type END_RESPONSE when done):${RESET}`);
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const responseLines = [];
+    await new Promise(resolve => {
+      const listener = line => {
+        if (line.trim() === 'END_RESPONSE') {
+          rl.removeListener('line', listener);
+          resolve();
+        } else responseLines.push(line);
+      };
+      rl.on('line', listener);
+    });
+    rl.close();
+    llmResponse = responseLines.join('\n');
+  }
+
+  console.log(`\n  ${DIM}[4/5] Parsing idioms/cases...${RESET}`);
+  let newIdioms = [];
+  let newCases = [];
+
+  if (isLogMode) {
+    const parsed = parseEvolutionYaml(llmResponse);
+    newIdioms = parsed.idioms;
+    newCases = parsed.cases;
+  } else {
+    newIdioms = parseLlmYamlResponse(llmResponse);
+  }
+
+  if (!newIdioms.length && !newCases.length) {
+    console.log(`  ${YELLOW}⚠ No idioms or cases extracted from LLM response.${RESET}`);
+    console.log(`\n`);
+    return;
+  }
+
+  if (newIdioms.length > 0) {
+    console.log(`  ${GREEN}✔ Extracted ${newIdioms.length} idiom(s)${RESET}`);
+    for (const idiom of newIdioms) {
+      console.log(`    ${CYAN}• ${idiom.pattern || '?'}${RESET}  — ${idiom.reason || ''}`);
+    }
+  }
+
+  if (newCases.length > 0) {
+    console.log(`  ${GREEN}✔ Extracted ${newCases.length} case precedent(s)${RESET}`);
+    for (const c of newCases) {
+      console.log(`    ${RED}• ${c.pattern || '?'}${RESET}  — ${c.reason || ''}`);
+    }
+  }
+
+  console.log(`\n  ${DIM}[5/5] Merging into project-idioms/SKILL.md...${RESET}`);
+  const existing = loadExistingIdioms();
+  const log = loadLog();
+  let nextId = nextIdiomId(existing);
+  const today = new Date().toISOString().slice(0, 10);
+  const merged = [...existing];
+  let added = 0;
+
+  for (const idiom of newIdioms) {
+    if (isDuplicateIdiom(idiom.pattern || '', existing)) {
+      console.log(`  ${DIM}  Skipped near-duplicate idiom: ${idiom.pattern}${RESET}`);
+      continue;
+    }
+    merged.push({
+      id: nextId,
+      pattern: idiom.pattern || '?',
+      reason: idiom.reason || 'No reason provided.',
+      domain: idiom.domain || 'general',
+      since: today,
+    });
+    nextId++;
+    added++;
+  }
+
+  if (added > 0) {
+    log.total_idioms = merged.length;
+    const skillMd = renderSkillMd(merged, (log.cycles || []).length + 1);
+    const { skillDir, skillFile } = getPaths();
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(skillFile, skillMd, 'utf8');
+    console.log(`  ${GREEN}✔ ${added} new idiom(s) added to SKILL.md${RESET}`);
+  } else {
+    console.log(`  ${DIM}  No new unique idioms added to SKILL.md.${RESET}`);
+  }
+
+  // Record Case Precedents if present
+  if (newCases && newCases.length > 0) {
+    console.log(`\n  ${DIM}Merging into Case Law precedents...${RESET}`);
+    const caseLawManager = require('./case_law_manager');
+    const clIndex = caseLawManager.loadIndex();
+    let clNextId = clIndex.next_id;
+    let clAdded = 0;
+
+    for (const c of newCases) {
+      const diffText = c.pattern || '';
+      const reason = c.reason || '';
+      const domain = c.domain || 'general';
+      const verdict = c.verdict || 'REJECTED';
+      const fingerprint = caseLawManager.contentHash(diffText);
+
+      let isDup = false;
+      for (const existing of clIndex.cases) {
+        if (existing.fingerprint === fingerprint) {
+          isDup = true;
+          break;
+        }
+      }
+      if (isDup) {
+        console.log(`  ${DIM}  Skipped duplicate case: ${reason.slice(0, 50)}...${RESET}`);
+        continue;
+      }
+
+      const deltaCase = caseLawManager.semanticDelta(diffText);
+      const tags = caseLawManager.extractTags(diffText + ' ' + reason);
+      const caseRecord = {
+        id: clNextId,
+        fingerprint,
+        timestamp: new Date().toISOString().slice(0, 19),
+        domain,
+        verdict,
+        reason: reason.trim(),
+        pr_ref: 'auto-evolution',
+        reviewer: 'skill-evolution',
+        tags,
+        stack_version: null,
+        diff_raw: diffText.trim(),
+        diff_delta: deltaCase,
+        auto_recorded: true,
+      };
+
+      caseLawManager.saveCase(caseRecord);
+      clIndex.cases.push({
+        id: clNextId,
+        fingerprint,
+        domain,
+        verdict,
+        tags,
+        timestamp: caseRecord.timestamp,
+        reason_summary: reason.trim().slice(0, 120),
+        stack_version: null,
+      });
+      clNextId++;
+      clAdded++;
+    }
+
+    if (clAdded > 0) {
+      clIndex.next_id = clNextId;
+      caseLawManager.saveIndex(clIndex);
+      console.log(`  ${GREEN}✔ ${clAdded} new Case Law precedent(s) recorded.${RESET}`);
+    } else {
+      console.log(`  ${DIM}  No new unique Case Law precedents recorded.${RESET}`);
+    }
+  }
+
+  log.cycles = log.cycles || [];
+  log.cycles.push({
+    timestamp: new Date().toISOString().slice(0, 19),
+    raw_tokens: rawTokens,
+    delta_tokens: deltaTokens,
+    tokens_saved: savedTokens,
+    idioms_added: added,
+  });
+  log.total_tokens_saved = (log.total_tokens_saved || 0) + savedTokens;
+  saveLog(log);
+
+  console.log(`\n  ${GREEN}✔ Learn cycle complete.${RESET}`);
+  console.log(`  ${DIM}   Total idioms: ${merged.length}${RESET}`);
+  console.log(`  ${DIM}   Lifetime tokens saved: ${log.total_tokens_saved}${RESET}\n`);
+}
+
+function cmdShow() {
+  const { skillFile } = getPaths();
+  if (!fs.existsSync(skillFile)) {
+    console.log(`${YELLOW}No project-idioms skill found. Run 'digest' first.${RESET}`);
+    return;
+  }
+  console.log(fs.readFileSync(skillFile, 'utf8'));
+}
+
+function cmdReset() {
+  const { skillFile, logFile } = getPaths();
+  if (fs.existsSync(skillFile)) {
+    fs.unlinkSync(skillFile);
+    console.log(`${GREEN}✔ project-idioms/SKILL.md deleted.${RESET}`);
+  }
+  if (fs.existsSync(logFile)) {
+    fs.unlinkSync(logFile);
+    console.log(`${GREEN}✔ Digest log cleared.${RESET}`);
+  }
+  console.log(`${DIM}Run 'digest' to start a fresh evolution cycle.${RESET}`);
+}
+
+function cmdStatus() {
+  const log = loadLog();
+  const cycles = log.cycles || [];
+  const totalSaved = log.total_tokens_saved || 0;
+  const totalIdioms = log.total_idioms || 0;
+  const { skillFile } = getPaths();
+  const idiomsExist = fs.existsSync(skillFile);
+
+  console.log(`\n${BOLD}${CYAN}━━━ Skill Evolution Status ━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  Digest cycles    : ${BOLD}${cycles.length}${RESET}`);
+  console.log(`  Total idioms     : ${BOLD}${totalIdioms}${RESET}`);
+  console.log(
+    `  Tokens saved     : ${GREEN}${totalSaved.toLocaleString()} tokens${RESET}  (≈ $${((totalSaved / 1_000_000) * 3).toFixed(4)} at $3/M)`,
+  );
+  console.log(`  SKILL.md exists  : ${idiomsExist ? '✔' : '✗'}`);
+
+  if (cycles.length) {
+    console.log(`\n  ${BOLD}Last 5 digest cycles:${RESET}`);
+    for (const cycle of cycles.slice(-5).reverse()) {
+      const ts = (cycle.timestamp || '?').slice(0, 16);
+      const deltaT = cycle.delta_tokens || 0;
+      const saved = cycle.tokens_saved || 0;
+      const addedCount = cycle.idioms_added || 0;
+      const pct = Math.floor((saved / Math.max(cycle.raw_tokens || 1, 1)) * 100);
+      console.log(
+        `    ${DIM}${ts}${RESET}  delta=${deltaT}tok  saved=${saved}tok (${pct}%)  idioms+=${addedCount}`,
+      );
+    }
+  }
+  console.log(`${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+const COMMANDS = {
+  digest: cmdDigest,
+  show: cmdShow,
+  reset: cmdReset,
+  status: cmdStatus,
+};
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (!argv.length || ['-h', '--help', 'help'].includes(argv[0])) {
+    console.log(`
+${BOLD}skill_evolution.js${RESET} — Tribunal Skill Evolution Forge
+
+${BOLD}Commands:${RESET}
+  digest [--dry-run] [--head]   Analyze latest git diff and evolve SKILL.md
+                                  --dry-run  : preview without writing
+                                  --head     : diff last commit instead of staged
+  show                           Print current project-idioms/SKILL.md
+  status                         Show digest history and token savings
+  reset                          Clear all idioms and start fresh
+
+${BOLD}Token Budget:${RESET}
+  Raw diff -> Semantic Filter -> Only architectural lines -> LLM
+  Typical savings: 70–90% of tokens. Most trivial commits = 0 tokens.
+`);
+    return;
+  }
+
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  if (!COMMANDS[cmd]) {
+    console.log(`${RED}✖ Unknown command: '${cmd}'${RESET}`);
+    process.exit(1);
+  }
+  await COMMANDS[cmd](rest);
+}
+
+module.exports = {
+  semanticDelta,
+  architecturalWeight,
+  parseLlmYamlResponse,
+  loadExistingIdioms,
+  getPaths,
+};
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}