chekk 0.5.4 → 1.0.0

package/src/insights.js

@@ -1,661 +0,0 @@
-/**
- * Insights Engine
- *
- * Computes higher-order analysis from raw metrics and sessions:
- * - Signatures: distinctive patterns that make an engineer unique
- * - Watch Points: anti-patterns and areas for improvement
- * - Trajectory: weekly score evolution over time
- * - Project Complexity: classification of project sophistication
- * - Assessment: narrative paragraph for the engineer's profile
- * - Confidence: statistical confidence based on data volume
- */
-
-import { computeDecomposition } from './metrics/decomposition.js';
-import { computeDebugCycles } from './metrics/debug-cycles.js';
-import { computeAILeverage } from './metrics/ai-leverage.js';
-import { computeSessionStructure } from './metrics/session-structure.js';
-import { computeOverallScore } from './scorer.js';
-
-// ── Benchmarks (early-stage estimates, refined as data grows) ──
-export const BENCHMARKS = {
-  avgExchangesPerSession: 34.2,
-  avgPromptLength: 187,
-  avgTurnsToResolve: 3.8,
-  specificReportRatio: 62,
-  highLevelRatio: 18,
-  contextSetRatio: 35,
-  refinementRatio: 15,
-  reviewEndRatio: 28,
-};
-
-// ── Dimension score ranges (observed distribution) ──
-export const DIM_RANGES = {
-  decomposition: { min: 15, max: 95 },
-  debugCycles: { min: 20, max: 98 },
-  aiLeverage: { min: 10, max: 92 },
-  sessionStructure: { min: 12, max: 88 },
-};
-
-// ══════════════════════════════════════════════
-// SIGNATURES — Distinctive patterns
-// ══════════════════════════════════════════════
-
-const constraintPatterns = /\b(don'?t|do not|never|avoid|without|no |not |shouldn'?t|must not|skip|exclude)\b/i;
-const preflightPatterns = /^(before (we|you|i)|don'?t code|review (first|this|my|the plan)|let'?s (think|plan|discuss)|check my (approach|plan|thinking))/i;
-const testFirstPatterns = /\b(write (the )?tests? (first|before)|test.?driven|TDD|spec first|start with (tests?|specs?))\b/i;
-const negativeConstraintPatterns = /\b(don'?t|do not|never|avoid|must not|shouldn'?t)\b.*\b(add|create|use|include|change|modify|touch|remove)\b/i;
-
-// Number formatting for insights text
-function numberFormatInsight(n) {
-  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
-  if (n >= 1000) return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k';
-  return String(n);
-}
-
-// Evidence quality filter (same rules as metric parsers)
-const noisePatterns = /^This session is being continued|^\[?[0-9T:.Z-]{20,}|^\S+@\S+.*[%$#>]|^\s*\$\s|^\s*>\s/;
-function isGoodEvidence(prompt) {
-  if (!prompt || prompt.length < 40 || prompt.length > 600) return false;
-  if (noisePatterns.test(prompt)) return false;
-  const alpha = prompt.replace(/[^a-zA-Z]/g, '').length;
-  if (alpha / prompt.length < 0.4) return false;
-  return true;
-}
-
-export function computeSignatures(allSessions, metrics, tokenEfficiency = null) {
-  const signatures = [];
-  const d = metrics.decomposition.details;
-  const db = metrics.debugCycles.details;
-  const ai = metrics.aiLeverage.details;
-  const ss = metrics.sessionStructure.details;
-
-  let totalPrompts = 0;
-  let constraintPrompts = 0;
-  let preflightSessions = 0;
-  let testFirstSessions = 0;
-  let modificationCount = 0;
-  let acceptCount = 0;
-
-  // Capture evidence prompts for each signature type
-  let bestPreflightPrompt = null;
-  let bestConstraintPrompt = null;
-  let bestTestFirstPrompt = null;
-  let bestModifyPrompt = null;
-
-  for (const session of allSessions) {
-    const { exchanges } = session;
-    if (exchanges.length === 0) continue;
-
-    // Check first prompt for preflight review
-    const firstPrompt = exchanges[0].userPrompt || '';
-    if (preflightPatterns.test(firstPrompt)) {
-      preflightSessions++;
-      if (isGoodEvidence(firstPrompt) && (!bestPreflightPrompt || firstPrompt.length > bestPreflightPrompt.length)) {
-        bestPreflightPrompt = firstPrompt;
-      }
-    }
-
-    let hasTestFirst = false;
-    for (let i = 0; i < exchanges.length; i++) {
-      const prompt = exchanges[i].userPrompt || '';
-      totalPrompts++;
-
-      if (constraintPatterns.test(prompt) && negativeConstraintPatterns.test(prompt)) {
-        constraintPrompts++;
-        if (isGoodEvidence(prompt) && (!bestConstraintPrompt || prompt.length > bestConstraintPrompt.length)) {
-          bestConstraintPrompt = prompt;
-        }
-      }
-
-      if (testFirstPatterns.test(prompt)) {
-        hasTestFirst = true;
-        if (isGoodEvidence(prompt) && (!bestTestFirstPrompt || prompt.length > bestTestFirstPrompt.length)) {
-          bestTestFirstPrompt = prompt;
-        }
-      }
-
-      // Track modification vs acceptance
-      if (i > 0 && /\b(actually|wait|instead|change|no,?|not quite|modify|tweak)\b/i.test(prompt)) {
-        modificationCount++;
-        if (isGoodEvidence(prompt) && (!bestModifyPrompt || prompt.length > bestModifyPrompt.length)) {
-          bestModifyPrompt = prompt;
-        }
-      } else if (i > 0) {
-        acceptCount++;
-      }
-    }
-    if (hasTestFirst) testFirstSessions++;
-  }
-
-  const sessionsWithExchanges = allSessions.filter(s => s.exchanges.length > 0).length;
-
-  // Pre-flight reviews
-  const preflightRatio = sessionsWithExchanges > 0 ? preflightSessions / sessionsWithExchanges : 0;
-  if (preflightRatio > 0.15 && preflightSessions >= 3) {
-    signatures.push({
-      name: 'Pre-flight reviews',
-      detail: `You ask AI to review your plan before coding in ${Math.round(preflightRatio * 100)}% of sessions. Only 8% of engineers do this consistently. This correlates with fewer debug cycles.`,
-      evidence: bestPreflightPrompt,
-    });
-  }
-
-  // Constraint-first prompting
-  const constraintRatio = totalPrompts > 0 ? constraintPrompts / totalPrompts : 0;
-  if (constraintRatio > 0.1 && constraintPrompts >= 5) {
-    signatures.push({
-      name: 'Constraint-first prompting',
-      detail: `You specify what NOT to do in ${Math.round(constraintRatio * 100)}% of prompts. This is a hallmark of senior architectural thinking that prevents scope creep.`,
-      evidence: bestConstraintPrompt,
-    });
-  }
-
-  // Test-driven AI usage
-  const testFirstRatio = sessionsWithExchanges > 0 ? testFirstSessions / sessionsWithExchanges : 0;
-  if (testFirstRatio > 0.05 && testFirstSessions >= 2) {
-    signatures.push({
-      name: 'Test-driven AI usage',
-      detail: `You request tests before implementation in ${Math.round(testFirstRatio * 100)}% of sessions. Engineers who do this ship fewer bugs post-merge.`,
-      evidence: bestTestFirstPrompt,
-    });
-  }
-
-  // Deep session marathons — evidence is metric-derived, no single prompt
-  if (d.avgExchangesPerSession > BENCHMARKS.avgExchangesPerSession * 2) {
-    signatures.push({
-      name: 'Marathon sessions',
-      detail: `Avg session depth of ${d.avgExchangesPerSession} exchanges is ${Math.round(d.avgExchangesPerSession / BENCHMARKS.avgExchangesPerSession)}x the benchmark (${BENCHMARKS.avgExchangesPerSession}). You sustain deep, focused work.`,
-      evidence: null,
-    });
-  }
-
-  // Zero vague debugging — evidence is the absence of something
-  if (db.vagueReports === 0 && db.totalDebugSequences > 5) {
-    signatures.push({
-      name: 'Precision debugging',
-      detail: `Zero vague error reports across ${db.totalDebugSequences} debug sequences. Every bug report includes specific context. This is rare.`,
-      evidence: metrics.debugCycles.examples?.[0]?.prompt || null,
-    });
-  }
-
-  // High architectural ratio
-  if (ai.highLevelRatio > 30) {
-    signatures.push({
-      name: 'Strategic AI usage',
-      detail: `${ai.highLevelRatio}% of prompts are architectural or planning-level (benchmark: ${BENCHMARKS.highLevelRatio}%). You use AI as a thinking partner, not just a code generator.`,
-      evidence: metrics.aiLeverage.examples?.[0]?.prompt || null,
-    });
-  }
-
-  // Critical reviewer
-  const totalFollowups = modificationCount + acceptCount;
-  const modRatio = totalFollowups > 0 ? modificationCount / totalFollowups : 0;
-  if (modRatio > 0.25 && modificationCount > 10) {
-    signatures.push({
-      name: 'Critical reviewer',
-      detail: `You modify or redirect AI output in ${Math.round(modRatio * 100)}% of follow-up prompts. This indicates active evaluation rather than passive acceptance.`,
-      evidence: bestModifyPrompt,
-    });
-  }
-
-  // ── Token-backed signature: efficient token usage ──
-  if (tokenEfficiency && tokenEfficiency.hasData) {
-    const te = tokenEfficiency;
-    // If context re-read ratio is below 90%, that's notably efficient
-    if (te.contextRereadRatio < 0.90 && te.sessionsAnalyzed >= 5) {
-      signatures.push({
-        name: 'Token-efficient prompting',
-        detail: `Only ${Math.round(te.contextRereadRatio * 100)}% of your tokens are context re-reads (typical: 95%+). Your focused sessions and clear prompts minimize wasted tokens. Estimated spend: $${te.estimatedCostTotal.toFixed(2)}.`,
-        evidence: null,
-      });
-    }
-  }
-
-  return signatures.slice(0, 4); // Max 4 signatures
-}
-
-// ══════════════════════════════════════════════
-// WATCH POINTS — Anti-patterns
-// ══════════════════════════════════════════════
-
-export function computeWatchPoints(allSessions, metrics, tokenEfficiency = null) {
-  const watchPoints = [];
-  const d = metrics.decomposition.details;
-  const db = metrics.debugCycles.details;
-  const ai = metrics.aiLeverage.details;
-  const ss = metrics.sessionStructure.details;
-
-  // Context amnesia — restarting from scratch on same project
-  const projectSessions = {};
-  for (const s of allSessions) {
-    const p = s.project || 'unknown';
-    if (!projectSessions[p]) projectSessions[p] = [];
-    projectSessions[p].push(s);
-  }
-  let contextRestarts = 0;
-  let bestContextRestartPrompt = null;
-  let multiSessionProjects = 0;
-  for (const [, sessions] of Object.entries(projectSessions)) {
-    if (sessions.length < 2) continue;
-    multiSessionProjects++;
-    for (let i = 1; i < sessions.length; i++) {
-      const firstPrompt = sessions[i].exchanges[0]?.userPrompt || '';
-      // If first prompt doesn't reference previous work, it's a context restart
-      if (firstPrompt.length > 50 && !/\b(continuing|following up|as discussed|last time|previously|where we left|earlier)\b/i.test(firstPrompt)) {
-        contextRestarts++;
-        if (isGoodEvidence(firstPrompt) && (!bestContextRestartPrompt || firstPrompt.length > bestContextRestartPrompt.length)) {
-          bestContextRestartPrompt = firstPrompt;
-        }
-      }
-    }
-  }
-  const totalFollowupSessions = Object.values(projectSessions).reduce((sum, s) => sum + Math.max(0, s.length - 1), 0);
-  if (totalFollowupSessions > 3 && contextRestarts / totalFollowupSessions > 0.5) {
-    // Estimate cost of context restarts — each restart forces full context re-read
-    let costNote = '';
-    if (tokenEfficiency && tokenEfficiency.hasData) {
-      const avgCostPerSession = tokenEfficiency.estimatedCostTotal / Math.max(1, tokenEfficiency.sessionsAnalyzed);
-      // The re-read cost of each restart scales with context size — estimate as % of avg session cost
-      const rereadPct = tokenEfficiency.contextRereadRatio || 0.94;
-      const wastedPerRestart = avgCostPerSession * rereadPct * 0.3; // ~30% of re-read is avoidable with context continuity
-      const totalWasted = wastedPerRestart * contextRestarts;
-      if (totalWasted > 1) {
-        costNote = ` Estimated wasted re-read cost: ~$${totalWasted.toFixed(0)}.`;
-      }
-    }
-    watchPoints.push({
-      name: 'Context amnesia',
-      detail: `You restart context from scratch in ${Math.round(contextRestarts / totalFollowupSessions * 100)}% of follow-up sessions on the same project. Engineers who maintain context across sessions are more efficient.${costNote}`,
-      evidence: bestContextRestartPrompt,
-    });
-  }
-
-  // Low modification rate — accepting AI output without review
-  let modCount = 0;
-  let followupCount = 0;
-  for (const session of allSessions) {
-    for (let i = 1; i < session.exchanges.length; i++) {
-      followupCount++;
-      const prompt = session.exchanges[i].userPrompt || '';
-      if (/\b(actually|wait|instead|change|no,?|not quite|modify|tweak|hmm|but )\b/i.test(prompt)) {
-        modCount++;
-      }
-    }
-  }
-  const modRatio = followupCount > 10 ? modCount / followupCount : 0.5;
-  if (modRatio < 0.15 && followupCount > 20) {
-    watchPoints.push({
-      name: 'Acceptance without review',
-      detail: `You accept AI output without modification in ${Math.round((1 - modRatio) * 100)}% of cases. Top engineers modify or redirect 30%+ of initial suggestions.`,
-      evidence: null, // Anti-pattern is the absence of modification
-    });
-  }
-
-  // Monologue prompting — excessively long first prompts
-  if (d.avgPromptLength > 2000) {
-    // Find a representative long prompt
-    let bestLongPrompt = null;
-    for (const s of allSessions) {
-      for (const ex of s.exchanges) {
-        const p = ex.userPrompt || '';
-        if (p.length > 1500 && p.length < 3000 && isGoodEvidence(p)) {
-          if (!bestLongPrompt || p.length > bestLongPrompt.length) bestLongPrompt = p;
-        }
-      }
-    }
-    // Dollar annotation: long prompts trigger large context re-reads each time
-    let monologueCostNote = '';
-    if (tokenEfficiency && tokenEfficiency.hasData) {
-      // Compare avg tokens for long vs short prompts from the prompt length analysis
-      const longBucket = tokenEfficiency.promptLengthAnalysis.find(b => b.label === '500+ chars');
-      const shortBucket = tokenEfficiency.promptLengthAnalysis.find(b => b.label === '20-100 chars');
-      if (longBucket && shortBucket && longBucket.avgCost && shortBucket.avgCost) {
-        const ratio = (longBucket.avgCost / shortBucket.avgCost).toFixed(1);
-        monologueCostNote = ` Long prompts cost ${ratio}x more per exchange ($${longBucket.avgCost.toFixed(2)} vs $${shortBucket.avgCost.toFixed(2)}).`;
-      }
-    }
-    watchPoints.push({
-      name: 'Monologue prompting',
-      detail: `Avg prompt length of ${d.avgPromptLength} chars is ${Math.round(d.avgPromptLength / BENCHMARKS.avgPromptLength)}x the benchmark. Breaking complex requests into 2-3 shorter prompts typically yields better AI output.${monologueCostNote}`,
-      evidence: bestLongPrompt,
-    });
-  }
-
-  // Low context-setting
-  if (ss.contextSetRatio < 20) {
-    let contextCostNote = '';
-    if (ss.tokenEvidence?.avgTokensPerExchangeWithContext && ss.tokenEvidence?.avgTokensPerExchangeNoContext) {
-      const pricing = tokenEfficiency && tokenEfficiency.hasData
-        ? tokenEfficiency.estimatedCostTotal / Math.max(1, tokenEfficiency.grandTotal) : 0;
-      if (pricing > 0) {
-        const withCtx = ss.tokenEvidence.avgTokensPerExchangeWithContext * pricing;
-        const noCtx = ss.tokenEvidence.avgTokensPerExchangeNoContext * pricing;
-        if (noCtx > withCtx * 1.1) {
-          contextCostNote = ` Sessions without context cost $${noCtx.toFixed(2)}/exchange vs $${withCtx.toFixed(2)} with context.`;
-        }
-      }
-    }
-    watchPoints.push({
-      name: 'Missing context',
-      detail: `Only ${ss.contextSetRatio}% of sessions start with context-setting (benchmark: ${BENCHMARKS.contextSetRatio}%). Upfront context leads to better first responses and fewer corrections.${contextCostNote}`,
-      evidence: null,
-    });
-  }
-
-  // Extended debug spirals
-  if (db.longLoops > 2) {
-    let loopCostStr = '';
-    if (db.tokenEvidence?.avgTokensLongLoop) {
-      const pricing = tokenEfficiency && tokenEfficiency.hasData
-        ? tokenEfficiency.estimatedCostTotal / Math.max(1, tokenEfficiency.grandTotal) : 0;
-      if (pricing > 0) {
-        const costPerLoop = db.tokenEvidence.avgTokensLongLoop * pricing;
-        loopCostStr = ` Each spiral costs ~$${costPerLoop.toFixed(2)}.`;
-      } else {
-        loopCostStr = ` Each spiral averages ${numberFormatInsight(db.tokenEvidence.avgTokensLongLoop)} tokens.`;
-      }
-    }
-    watchPoints.push({
-      name: 'Debug spirals',
-      detail: `${db.longLoops} extended debug loops (>5 turns) detected.${loopCostStr} When stuck, try providing more specific error context or breaking the problem differently.`,
-      evidence: null,
-    });
-  }
-
-  // ── Token-backed watch points ──
-  if (tokenEfficiency && tokenEfficiency.hasData) {
-    const te = tokenEfficiency;
-
-    // Marathon sessions burning disproportionate tokens
-    const marathonSessions = te.costliestSessions.filter(s => s.exchanges > 50);
-    if (marathonSessions.length >= 2) {
-      const marathonCost = marathonSessions.reduce((s, m) => s + m.estimatedCost, 0);
-      const marathonPct = te.estimatedCostTotal > 0 ? Math.round(marathonCost / te.estimatedCostTotal * 100) : 0;
-      if (marathonPct > 40) {
-        watchPoints.push({
-          name: 'Marathon session tax',
-          detail: `${marathonSessions.length} marathon sessions (50+ exchanges) consumed ~${marathonPct}% of your total spend (~$${marathonCost.toFixed(2)}). Context compounds — splitting into focused sessions would reduce token waste.`,
-          evidence: null,
-        });
-      }
-    }
-
-    // Vague prompts costing more than specific ones
-    const vagueAvg = db.tokenEvidence?.avgTokensVagueDebug;
-    const specificAvg = db.tokenEvidence?.avgTokensSpecificDebug;
-    if (vagueAvg && specificAvg && vagueAvg > specificAvg * 1.5 && db.vagueReports > 3) {
-      watchPoints.push({
-        name: 'Vague prompts are expensive',
-        detail: `Your vague debug prompts average ${numberFormatInsight(vagueAvg)} tokens vs ${numberFormatInsight(specificAvg)} for specific ones — ${(vagueAvg / specificAvg).toFixed(1)}x more expensive. Adding error details upfront saves real money.`,
-        evidence: null,
-      });
-    }
-  }
-
-  return watchPoints.slice(0, 4); // Max 4 watch points (was 3, expanded for token insights)
-}
-
-// ══════════════════════════════════════════════
-// TRAJECTORY — Weekly score evolution
-// ══════════════════════════════════════════════
-
-export function computeTrajectory(allSessions) {
-  // Group sessions by week
-  const sessionsWithTime = allSessions.filter(s => s.startTime);
-  if (sessionsWithTime.length < 5) return null;
-
-  sessionsWithTime.sort((a, b) => new Date(a.startTime) - new Date(b.startTime));
-
-  const firstDate = new Date(sessionsWithTime[0].startTime);
-  const lastDate = new Date(sessionsWithTime[sessionsWithTime.length - 1].startTime);
-
-  // Need at least 2 weeks of data
-  const daySpan = (lastDate - firstDate) / (1000 * 60 * 60 * 24);
-  if (daySpan < 10) return null;
-
-  // Create weekly buckets
-  const weeks = [];
-  let weekStart = new Date(firstDate);
-  weekStart.setHours(0, 0, 0, 0);
-  // Align to Monday
-  weekStart.setDate(weekStart.getDate() - weekStart.getDay() + 1);
-
-  while (weekStart <= lastDate) {
-    const weekEnd = new Date(weekStart);
-    weekEnd.setDate(weekEnd.getDate() + 7);
-    const weekSessions = sessionsWithTime.filter(s => {
-      const t = new Date(s.startTime);
-      return t >= weekStart && t < weekEnd;
-    });
-
-    if (weekSessions.length >= 2) {
-      // Compute score for this week
-      const m = {
-        decomposition: computeDecomposition(weekSessions),
-        debugCycles: computeDebugCycles(weekSessions),
-        aiLeverage: computeAILeverage(weekSessions),
-        sessionStructure: computeSessionStructure(weekSessions),
-      };
-      const r = computeOverallScore(m);
-      const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-      weeks.push({
-        label: `${months[weekStart.getMonth()]} ${weekStart.getDate()}-${weekEnd.getDate() - 1}`,
-        score: r.overall,
-        sessions: weekSessions.length,
-      });
-    }
-
-    weekStart = new Date(weekStart);
-    weekStart.setDate(weekStart.getDate() + 7);
-  }
-
-  if (weeks.length < 2) return null;
-
-  // Compute learning velocity
-  const firstScore = weeks[0].score;
-  const lastScore = weeks[weeks.length - 1].score;
-  const delta = lastScore - firstScore;
-  const weeksCount = weeks.length;
-  const velocityPerWeek = delta / weeksCount;
-
-  let velocityLabel;
-  if (velocityPerWeek > 3) velocityLabel = 'FAST';
-  else if (velocityPerWeek > 1) velocityLabel = 'STEADY';
-  else if (velocityPerWeek > -1) velocityLabel = 'STABLE';
-  else velocityLabel = 'DECLINING';
-
-  return {
-    weeks,
-    delta,
-    daysSpan: Math.round(daySpan),
-    velocityLabel,
-    velocityDetail: delta !== 0
-      ? `${Math.abs(delta)} point ${delta > 0 ? 'improvement' : 'change'} over ${Math.round(daySpan)} days`
-      : `Stable over ${Math.round(daySpan)} days`,
-  };
-}
-
-// ══════════════════════════════════════════════
-// PROJECT COMPLEXITY — What did they build?
-// ══════════════════════════════════════════════
-
-const complexitySignals = {
-  high: /\b(pipeline|distributed|real.?time|analytics|classification|machine learning|ml |auth|oauth|websocket|streaming|queue|worker|migration|microservice|kubernetes|docker|deployment|ci.?cd|infrastructure|database design|data model|schema design|api design|caching|rate limit)\b/i,
-  medium: /\b(api|crud|component|feature|integration|testing|refactor|database|query|endpoint|route|middleware|hook|state management|responsive|animation|chart|graph|dashboard)\b/i,
-};
-
-export function computeProjectComplexity(allSessions) {
-  const projectData = {};
-
-  for (const s of allSessions) {
-    const p = s.project || 'unknown';
-    if (!projectData[p]) {
-      projectData[p] = { sessions: 0, exchanges: 0, daysActive: new Set(), highSignals: new Set(), medSignals: new Set(), prompts: [] };
-    }
-    projectData[p].sessions++;
-    projectData[p].exchanges += s.exchangeCount;
-    if (s.startTime) {
-      projectData[p].daysActive.add(new Date(s.startTime).toISOString().split('T')[0]);
-    }
-
-    for (const ex of s.exchanges) {
-      const prompt = ex.userPrompt || '';
-      projectData[p].prompts.push(prompt);
-
-      // Extract complexity signals
-      const highMatches = prompt.match(complexitySignals.high);
-      const medMatches = prompt.match(complexitySignals.medium);
-      if (highMatches) {
-        for (const m of highMatches) projectData[p].highSignals.add(m.toLowerCase().trim());
-      }
-      if (medMatches) {
-        for (const m of medMatches) projectData[p].medSignals.add(m.toLowerCase().trim());
-      }
-    }
-  }
-
-  const projects = [];
-  for (const [name, data] of Object.entries(projectData)) {
-    if (data.exchanges < 3) continue; // Skip trivial projects
-
-    let complexity;
-    const signals = [...data.highSignals, ...data.medSignals].slice(0, 5);
-    if (data.highSignals.size >= 3 || (data.highSignals.size >= 1 && data.exchanges > 50)) {
-      complexity = 'HIGH';
-    } else if (data.medSignals.size >= 3 || data.highSignals.size >= 1 || data.exchanges > 30) {
-      complexity = 'MEDIUM';
-    } else {
-      complexity = 'LOW';
-    }
-
-    const shortName = name.length > 28 ? '...' + name.slice(-25) : name;
-
-    projects.push({
-      name: shortName,
-      complexity,
-      sessions: data.sessions,
-      exchanges: data.exchanges,
-      daysActive: data.daysActive.size,
-      signals,
-    });
-  }
-
-  // Sort by exchanges descending
-  projects.sort((a, b) => b.exchanges - a.exchanges);
-  return projects.slice(0, 5); // Top 5 projects
-}
-
-// ══════════════════════════════════════════════
-// ASSESSMENT — Narrative paragraph
-// ══════════════════════════════════════════════
-
-export function generateAssessment(result, metrics, signatures, watchPoints) {
-  const { overall, scores, archetype, tier } = result;
-  const d = metrics.decomposition.details;
-  const db = metrics.debugCycles.details;
-  const ai = metrics.aiLeverage.details;
-  const ss = metrics.sessionStructure.details;
-
-  // Find strongest and weakest dimensions
-  const dims = [
-    { key: 'decomposition', label: 'problem decomposition', score: scores.decomposition },
-    { key: 'debugCycles', label: 'debugging efficiency', score: scores.debugCycles },
-    { key: 'aiLeverage', label: 'AI leverage', score: scores.aiLeverage },
-    { key: 'sessionStructure', label: 'workflow discipline', score: scores.sessionStructure },
-  ];
-  dims.sort((a, b) => b.score - a.score);
-  const strongest = dims[0];
-  const weakest = dims[dims.length - 1];
-
-  // Build assessment parts
-  let assessment = `This engineer demonstrates ${dimQualitative(strongest.score).toLowerCase()} ${strongest.label}`;
-
-  // Add signature mention if available
-  if (signatures.length > 0) {
-    assessment += ` with a distinctive pattern of ${formatSignatureName(signatures[0].name)}`;
-  }
-  assessment += '.';
-
-  // Second sentence — second strength or debugging detail
-  if (dims[1].score >= 65) {
-    assessment += ` Their ${dims[1].label} is also ${dimQualitative(dims[1].score).toLowerCase()}`;
-    if (db.avgTurnsToResolve <= 2 && dims[1].key === 'debugCycles') {
-      assessment += ' \u2014 surgical and specific with ' + (db.longLoops === 0 ? 'zero' : 'minimal') + ' extended loops';
-    }
-    assessment += '.';
-  }
-
-  // Third sentence — growth area
-  if (weakest.score < 65) {
-    assessment += ` Primary growth opportunity is in ${weakest.label}`;
-    if (weakest.key === 'sessionStructure') {
-      assessment += ': context-setting and upfront planning are below benchmark';
-      if (ss.refinementRatio > 15) {
-        assessment += ', though iterative refinement partially compensates';
-      }
-    } else if (weakest.key === 'decomposition') {
-      assessment += ': more task breakdown and structured thinking would yield significant score improvement';
-    } else if (weakest.key === 'aiLeverage') {
-      assessment += ': using AI for architecture and planning, not just code generation, would increase impact';
-    } else {
-      assessment += ': stronger error reporting and systematic resolution would improve efficiency';
-    }
-    assessment += '.';
-  }
-
-  // Fourth sentence — best for
-  assessment += ' ' + archetype.bestFor;
-
-  return assessment;
-}
-
-function dimQualitative(score) {
-  if (score >= 80) return 'Exceptional';
-  if (score >= 65) return 'Strong';
-  if (score >= 50) return 'Solid';
-  if (score >= 35) return 'Developing';
-  return 'Early-stage';
-}
-
-// Lowercase a signature name for prose while preserving acronyms like "AI", "TDD"
-function formatSignatureName(name) {
-  return name
-    .toLowerCase()
-    .replace(/\bai\b/g, 'AI')
-    .replace(/\btdd\b/g, 'TDD');
-}
-
-// ══════════════════════════════════════════════
-// CONFIDENCE — Data volume indicator
-// ══════════════════════════════════════════════
-
-export function computeConfidence(sessionStats) {
-  const { totalSessions, totalExchanges, tools } = sessionStats;
-  const toolCount = tools.length;
-
-  // Score confidence on sessions, exchanges, and tool diversity
-  let score = 0;
-  if (totalSessions >= 50) score += 40;
-  else if (totalSessions >= 20) score += 30;
-  else if (totalSessions >= 10) score += 20;
-  else score += 10;
-
-  if (totalExchanges >= 500) score += 30;
-  else if (totalExchanges >= 200) score += 20;
-  else if (totalExchanges >= 50) score += 10;
-
-  if (toolCount >= 3) score += 20;
-  else if (toolCount >= 2) score += 15;
-  else score += 10;
-
-  // Bonus for enough data
-  if (totalSessions >= 30 && totalExchanges >= 300) score += 10;
-
-  score = Math.min(100, score);
-
-  let level;
-  if (score >= 80) level = 'HIGH';
-  else if (score >= 50) level = 'MODERATE';
-  else level = 'LOW';
-
-  return { score, level };
-}