smart-context-mcp 1.0.4 → 1.2.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.0.4",
-  "description": "MCP server that reduces agent token usage and improves response quality with compact file summaries, ranked code search, and curated context.",
+  "version": "1.2.0",
+  "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Arrayo/devctx-mcp-mvp.git"
+    "url": "git+https://github.com/Arrayo/smart-context-mcp.git"
   },
-  "homepage": "https://github.com/Arrayo/devctx-mcp-mvp#readme",
+  "homepage": "https://github.com/Arrayo/smart-context-mcp#readme",
   "bugs": {
-    "url": "https://github.com/Arrayo/devctx-mcp-mvp/issues"
+    "url": "https://github.com/Arrayo/smart-context-mcp/issues"
   },
   "bin": {
     "smart-context-headless": "scripts/headless-wrapper.js",
@@ -30,7 +30,8 @@
     "scripts/devctx-server.js",
     "scripts/headless-wrapper.js",
     "scripts/init-clients.js",
-    "scripts/report-metrics.js"
+    "scripts/report-metrics.js",
+    "scripts/report-workflow-metrics.js"
   ],
   "engines": {
     "node": ">=18"
@@ -51,12 +52,15 @@
     "init:clients": "node ./scripts/init-clients.js",
     "smoke:formats": "node ./scripts/format-smoke.js",
     "test": "node --test --test-concurrency=1 ./tests/*.test.js",
+    "verify": "node ./scripts/verify-features-direct.js",
+    "benchmark": "node ./scripts/run-benchmark.js",
     "eval": "node ./evals/harness.js",
     "eval:context": "node ./evals/harness.js --tool=context",
     "eval:both": "node ./evals/harness.js --tool=both",
     "eval:self": "node ./evals/harness.js --root=../.. --corpus=./evals/corpus/self-tasks.json",
     "eval:report": "node ./evals/report.js",
-    "report:metrics": "node ./scripts/report-metrics.js"
+    "report:metrics": "node ./scripts/report-metrics.js",
+    "report:workflows": "node ./scripts/report-workflow-metrics.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.0",

package/scripts/init-clients.js

@@ -375,42 +375,71 @@ const updatePreCommitHook = (targetDir, dryRun) => {
 // Agent rules — instruct agents to prefer devctx tools over built-in ones
 // ---------------------------------------------------------------------------
 
-const agentRuleBody = `Always prefer devctx MCP tools over built-in file reading, code search, diagnostics, and context recovery.
-
-- For every non-trivial user prompt, start with smart_turn phase=start before exploring the codebase. Pass the current user prompt and ensureSession=true for a meaningful new task.
-- Treat smart_turn phase=start as the default entrypoint for context recovery instead of manually deciding whether to call smart_summary(get).
-- Inspect repoSafety from smart_turn or smart_summary responses. If .devctx/state.sqlite is tracked or staged, mutating context writes are blocked until git hygiene is fixed.
-- If smart_turn phase=start reports ambiguous_resume, choose the recommended session explicitly with smart_summary sessionId="auto" before continuing.
-- After meaningful milestones, end the turn with smart_turn phase=end and the appropriate event (milestone, decision, blocker, task_complete, session_end) so persistence stays event-driven.
-- Before ending work, persist the latest nextStep with smart_turn phase=end and event=session_end.
-- Use smart_read outline or signatures before full (~90% token savings).
-- Use smart_read symbol (string or array) to extract specific functions/classes before editing.
-- Use smart_read range for specific lines when you know the location.
-- Use full mode only when outline/signatures/symbol are insufficient.
-- Use smart_search instead of grep/ripgrep — it groups, ranks, and filters automatically.
-- Pass intent to smart_search to get task-aware ranking (implementation/debug/tests/config/docs/explore).
-- Use smart_shell for diagnostics: git status, ls, find, pwd, test output.
-- Use smart_metrics to report token savings or recent devctx usage instead of reading metrics files manually.
-
-By task:
-- Debugging: smart_turn(start) → smart_search with intent=debug → read signatures → inspect symbol → smart_shell for tests/errors → smart_turn(end event=milestone or blocker).
-- Review: smart_turn(start) → smart_search with intent=implementation → read outline/signatures, focus on changed symbols, minimal changes → smart_turn(end event=milestone).
-- Refactor: smart_turn(start) → smart_search with intent=implementation → signatures for public API, preserve behavior, small edits, verify with tests → smart_turn(end event=milestone).
-- Tests: smart_turn(start) → smart_search with intent=tests → find existing tests, read symbol of function under test → smart_turn(end event=milestone).
-- Config: smart_search with intent=config → find settings, env vars, infrastructure files.
-- Architecture: smart_turn(start) → smart_search with intent=explore → directory structure, outlines of key modules and API boundaries → smart_turn(end event=task_switch or milestone).`;
+const agentRuleBody = `**First time in project?** Run build_index to enable search/context quality.
+
+Prefer devctx MCP for non-trivial tasks:
+- smart_read(outline|signatures|symbol) instead of Read → 90% savings
+- smart_search(intent=...) instead of Grep → ranked results
+- smart_context instead of multiple reads → one-call builder
+- smart_shell instead of Shell → safe diagnostics
+
+For non-trivial tasks: smart_turn(start) → [work with devctx tools] → smart_turn(end)
+
+Reading cascade: outline → signatures → symbol → full (last resort)
+
+Detailed workflows: .cursor/rules/profiles-compact/ (debugging, code-review, refactoring, testing, architecture)
+
+---
+
+If you didn't use devctx tools in a non-trivial programming task, add at the end:
+
+**Note:** devctx not used because: [task too simple | MCP unavailable | index not built | already had sufficient context | native tool more direct for this case]. To use devctx next time: "Use smart-context-mcp: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)"`;
 
 const cursorRuleContent = `---
-description: Prefer devctx MCP tools for file reading, code search, and diagnostics
+description: Prefer devctx MCP tools for non-trivial tasks
 alwaysApply: true
 ---
 
 ${agentRuleBody}
 `;
 
+const cursorProfilesNote = `
+# Task-Specific Profiles
+
+For detailed workflows, see rules in this directory:
+- debugging.mdc - Error-first, symbol-focused (90% savings)
+- code-review.mdc - Diff-aware, API-focused (87% savings)
+- refactoring.mdc - Graph-aware, test-verified (89% savings)
+- testing.mdc - Coverage-aware, TDD-friendly (90% savings)
+- architecture.mdc - Index-first, minimal-detail (90% savings)
+
+These profiles are **conditionally applied** based on file globs and task context.
+The base rule (devctx.mdc) is **always active** but kept minimal to reduce fixed context cost.
+`;
+
 const updateCursorRule = (targetDir, dryRun) => {
-  const filePath = path.join(targetDir, '.cursor', 'rules', 'devctx.mdc');
-  writeFile(filePath, cursorRuleContent, dryRun);
+  const rulesDir = path.join(targetDir, '.cursor', 'rules');
+  const profilesDir = path.join(rulesDir, 'profiles-compact');
+  
+  // Write base rule (always active)
+  const baseFilePath = path.join(rulesDir, 'devctx.mdc');
+  writeFile(baseFilePath, cursorRuleContent, dryRun);
+  
+  // Write profiles README
+  const profilesReadmePath = path.join(profilesDir, 'README.md');
+  writeFile(profilesReadmePath, cursorProfilesNote, dryRun);
+  
+  // Copy compact profiles from package
+  const sourceProfilesDir = path.join(devctxDir, 'agent-rules', 'profiles-compact');
+  if (fs.existsSync(sourceProfilesDir)) {
+    const profiles = fs.readdirSync(sourceProfilesDir).filter(f => f.endsWith('.mdc'));
+    profiles.forEach(profile => {
+      const sourcePath = path.join(sourceProfilesDir, profile);
+      const targetPath = path.join(profilesDir, profile);
+      const content = fs.readFileSync(sourcePath, 'utf8');
+      writeFile(targetPath, content, dryRun);
+    });
+  }
 };
 
 const SECTION_START = '<!-- devctx:start -->';

package/scripts/report-metrics.js

@@ -2,6 +2,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { smartMetrics } from '../src/tools/smart-metrics.js';
+import { formatAdoptionReport } from '../src/analytics/adoption.js';
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];
@@ -88,6 +89,10 @@ const printHuman = (report) => {
       `  ${tool.tool.padEnd(14)} count=${formatNumber(tool.count)} raw=${formatNumber(tool.rawTokens)} final=${formatNumber(tool.compressedTokens)} saved=${formatNumber(tool.savedTokens)} (${tool.savingsPct}%)`
     );
   }
+  
+  if (report.adoption) {
+    console.log(formatAdoptionReport(report.adoption));
+  }
 };
 
 export const main = async () => {

package/scripts/report-workflow-metrics.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Dynamic import to handle SQLite availability
+let workflowTracker;
+try {
+  workflowTracker = await import('../src/workflow-tracker.js');
+} catch {
+  workflowTracker = await import('../src/workflow-tracker-stub.js');
+}
+
+const { getWorkflowMetrics, getWorkflowSummaryByType, WORKFLOW_DEFINITIONS } = workflowTracker;
+
+const parseArgs = (argv) => {
+  const options = {
+    type: null,
+    sessionId: null,
+    limit: 10,
+    json: false,
+    summary: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--type') {
+      options.type = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === '--session') {
+      options.sessionId = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === '--limit') {
+      options.limit = parseInt(argv[index + 1], 10);
+      index += 1;
+      continue;
+    }
+
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (token === '--summary') {
+      options.summary = true;
+      continue;
+    }
+
+    if (token === '--help' || token === '-h') {
+      console.log(`
+Usage: report-workflow-metrics [options]
+
+Options:
+  --type <type>       Filter by workflow type (debugging, code-review, refactoring, testing, architecture)
+  --session <id>      Filter by session ID
+  --limit <n>         Limit number of workflows (default: 10)
+  --summary           Show summary by workflow type
+  --json              Output as JSON
+  --help, -h          Show this help
+
+Examples:
+  # Show summary by workflow type
+  npm run report:workflows -- --summary
+
+  # Show last 10 debugging workflows
+  npm run report:workflows -- --type debugging
+
+  # Show workflows for specific session
+  npm run report:workflows -- --session abc123
+
+  # Output as JSON
+  npm run report:workflows -- --json
+      `);
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+};
+
+const formatNumber = (value) => new Intl.NumberFormat('en-US').format(value);
+
+const formatDuration = (ms) => {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
+  return `${(ms / 3600000).toFixed(1)}h`;
+};
+
+const printSummary = (summary) => {
+  console.log('');
+  console.log('Workflow Metrics Summary');
+  console.log('═'.repeat(120));
+  console.log('');
+
+  if (!Array.isArray(summary) || summary.length === 0) {
+    console.log('No completed workflows found.');
+    console.log('');
+    console.log('Workflows are tracked when:');
+    console.log('  1. Agent calls smart_turn(start) with a task description');
+    console.log('  2. Task matches a workflow pattern (debugging, review, refactor, testing, architecture)');
+    console.log('  3. Agent calls smart_turn(end) to complete the workflow');
+    console.log('');
+    return;
+  }
+
+  const totalWorkflows = summary.reduce((sum, s) => sum + s.count, 0);
+  const totalRaw = summary.reduce((sum, s) => sum + s.total_raw_tokens, 0);
+  const totalCompressed = summary.reduce((sum, s) => sum + s.total_compressed_tokens, 0);
+  const totalSaved = summary.reduce((sum, s) => sum + s.total_saved_tokens, 0);
+  const totalBaseline = summary.reduce((sum, s) => sum + s.total_baseline_tokens, 0);
+
+  console.log(`Total Workflows: ${formatNumber(totalWorkflows)}`);
+  console.log(`Total Raw Tokens: ${formatNumber(totalRaw)}`);
+  console.log(`Total Compressed Tokens: ${formatNumber(totalCompressed)}`);
+  console.log(`Total Saved Tokens: ${formatNumber(totalSaved)} (${((totalSaved / totalRaw) * 100).toFixed(2)}%)`);
+  console.log(`Total Baseline Tokens: ${formatNumber(totalBaseline)}`);
+  console.log(`Savings vs Baseline: ${formatNumber(totalBaseline - totalCompressed)} (${(((totalBaseline - totalCompressed) / totalBaseline) * 100).toFixed(2)}%)`);
+  console.log('');
+  console.log('By Workflow Type:');
+  console.log('─'.repeat(120));
+  console.log(
+    'Type'.padEnd(20) +
+      'Count'.padStart(8) +
+      'Avg Steps'.padStart(12) +
+      'Avg Duration'.padStart(15) +
+      'Avg Savings'.padStart(15) +
+      'vs Baseline'.padStart(15),
+  );
+  console.log('─'.repeat(120));
+
+  for (const s of summary) {
+    const def = WORKFLOW_DEFINITIONS[s.workflow_type];
+    const name = def ? def.name : s.workflow_type;
+
+    console.log(
+      name.padEnd(20) +
+        formatNumber(s.count).padStart(8) +
+        s.avgStepsCount.toString().padStart(12) +
+        formatDuration(s.avgDurationMs).padStart(15) +
+        `${s.avgSavingsPct}%`.padStart(15) +
+        `${s.avgVsBaselinePct}%`.padStart(15),
+    );
+  }
+
+  console.log('─'.repeat(120));
+  console.log('');
+
+  // Show detailed breakdown for each workflow type
+  console.log('Detailed Breakdown:');
+  console.log('');
+
+  for (const s of summary) {
+    const def = WORKFLOW_DEFINITIONS[s.workflow_type];
+    const name = def ? def.name : s.workflow_type;
+
+    console.log(`${name}:`);
+    console.log(`  Workflows: ${formatNumber(s.count)}`);
+    console.log(`  Avg Steps: ${s.avgStepsCount}`);
+    console.log(`  Avg Duration: ${formatDuration(s.avgDurationMs)}`);
+    console.log(`  Total Raw Tokens: ${formatNumber(s.total_raw_tokens)}`);
+    console.log(`  Total Compressed Tokens: ${formatNumber(s.total_compressed_tokens)}`);
+    console.log(`  Total Saved Tokens: ${formatNumber(s.total_saved_tokens)} (${s.avgSavingsPct}%)`);
+    console.log(`  Baseline Tokens: ${formatNumber(s.total_baseline_tokens)}`);
+    console.log(`  Savings vs Baseline: ${formatNumber(s.total_baseline_tokens - s.total_compressed_tokens)} (${s.avgVsBaselinePct}%)`);
+    console.log('');
+  }
+};
+
+const printWorkflows = (workflows) => {
+  console.log('');
+  console.log('Recent Workflows');
+  console.log('═'.repeat(120));
+  console.log('');
+
+  if (workflows.length === 0) {
+    console.log('No workflows found.');
+    console.log('');
+    return;
+  }
+
+  for (const w of workflows) {
+    const def = WORKFLOW_DEFINITIONS[w.workflow_type];
+    const name = def ? def.name : w.workflow_type;
+    const status = w.end_time ? '✓ Completed' : '⏳ In Progress';
+
+    console.log(`${name} (${status})`);
+    console.log(`  Workflow ID: ${w.workflow_id}`);
+    console.log(`  Session ID: ${w.session_id || 'N/A'}`);
+    console.log(`  Started: ${new Date(w.start_time).toLocaleString()}`);
+
+    if (w.end_time) {
+      console.log(`  Ended: ${new Date(w.end_time).toLocaleString()}`);
+      console.log(`  Duration: ${formatDuration(w.duration_ms)}`);
+      console.log(`  Steps: ${w.steps_count}`);
+      console.log(`  Tools Used: ${w.toolsUsed.join(', ')}`);
+      console.log(`  Raw Tokens: ${formatNumber(w.raw_tokens)}`);
+      console.log(`  Compressed Tokens: ${formatNumber(w.compressed_tokens)}`);
+      console.log(`  Saved Tokens: ${formatNumber(w.saved_tokens)} (${w.savings_pct}%)`);
+      console.log(`  Baseline Tokens: ${formatNumber(w.baseline_tokens)}`);
+      console.log(`  Savings vs Baseline: ${formatNumber(w.baseline_tokens - w.compressed_tokens)} (${w.vs_baseline_pct}%)`);
+    }
+
+    console.log('');
+  }
+};
+
+const main = async () => {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+
+    if (options.summary) {
+      const summary = getWorkflowSummaryByType();
+
+      if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+      }
+
+      printSummary(summary);
+      return;
+    }
+
+    const workflows = getWorkflowMetrics({
+      workflowType: options.type,
+      sessionId: options.sessionId,
+      limit: options.limit,
+      completed: true,
+    });
+
+    if (options.json) {
+      console.log(JSON.stringify(workflows, null, 2));
+      return;
+    }
+
+    printWorkflows(workflows);
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+};
+
+const isDirectExecution = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectExecution) {
+  main();
+}

package/src/analytics/adoption.js

@@ -0,0 +1,197 @@
+/**
+ * Adoption analytics - measures how often agents use devctx tools in practice
+ * 
+ * Limitations:
+ * - Complexity is inferred from operation count, not actual task complexity
+ * - Can't detect feedback shown (requires agent cooperation)
+ * - Can't detect forcing prompts (requires prompt analysis)
+ * - Can only measure when devctx IS used, not when it's ignored
+ */
+
+const DEVCTX_TOOLS = new Set([
+  'smart_read',
+  'smart_search',
+  'smart_context',
+  'smart_shell',
+  'smart_summary',
+  'smart_turn',
+  'smart_read_batch',
+  'smart_metrics',
+  'build_index',
+  'warm_cache',
+  'git_blame',
+  'cross_project',
+]);
+
+const inferComplexity = (opCount, fileCount) => {
+  if (opCount <= 2 && fileCount <= 1) return 'trivial';
+  if (opCount <= 5 && fileCount <= 3) return 'simple';
+  if (opCount <= 15 && fileCount <= 10) return 'moderate';
+  return 'complex';
+};
+
+const groupBySession = (entries) => {
+  const sessions = new Map();
+  
+  for (const entry of entries) {
+    const sessionId = entry.sessionId || entry.session_id || 'unknown';
+    
+    if (!sessions.has(sessionId)) {
+      sessions.set(sessionId, {
+        sessionId,
+        operations: [],
+        devctxTools: new Set(),
+        nativeTools: new Set(),
+        filesAccessed: new Set(),
+        totalRawTokens: 0,
+        totalCompressedTokens: 0,
+        totalSavedTokens: 0,
+      });
+    }
+    
+    const session = sessions.get(sessionId);
+    session.operations.push(entry);
+    
+    const tool = entry.tool;
+    if (DEVCTX_TOOLS.has(tool)) {
+      session.devctxTools.add(tool);
+    } else if (tool) {
+      session.nativeTools.add(tool);
+    }
+    
+    if (entry.target) {
+      session.filesAccessed.add(entry.target);
+    }
+    
+    session.totalRawTokens += Number(entry.rawTokens || entry.raw_tokens || 0);
+    session.totalCompressedTokens += Number(entry.compressedTokens || entry.compressed_tokens || 0);
+    session.totalSavedTokens += Number(entry.savedTokens || entry.saved_tokens || 0);
+  }
+  
+  return Array.from(sessions.values());
+};
+
+export const analyzeAdoption = (entries) => {
+  const sessions = groupBySession(entries);
+  
+  const sessionsWithDevctx = sessions.filter(s => s.devctxTools.size > 0);
+  const sessionsWithoutDevctx = sessions.filter(s => s.devctxTools.size === 0 && s.operations.length > 0);
+  
+  const byComplexity = {
+    trivial: { total: 0, withDevctx: 0 },
+    simple: { total: 0, withDevctx: 0 },
+    moderate: { total: 0, withDevctx: 0 },
+    complex: { total: 0, withDevctx: 0 },
+  };
+  
+  for (const session of sessions) {
+    const complexity = inferComplexity(session.operations.length, session.filesAccessed.size);
+    byComplexity[complexity].total += 1;
+    if (session.devctxTools.size > 0) {
+      byComplexity[complexity].withDevctx += 1;
+    }
+  }
+  
+  const nonTrivialSessions = sessions.filter(s => {
+    const complexity = inferComplexity(s.operations.length, s.filesAccessed.size);
+    return complexity !== 'trivial';
+  });
+  
+  const nonTrivialWithDevctx = nonTrivialSessions.filter(s => s.devctxTools.size > 0);
+  
+  const toolUsageCount = {};
+  for (const session of sessionsWithDevctx) {
+    for (const tool of session.devctxTools) {
+      toolUsageCount[tool] = (toolUsageCount[tool] || 0) + 1;
+    }
+  }
+  
+  return {
+    totalSessions: sessions.length,
+    sessionsWithDevctx: sessionsWithDevctx.length,
+    sessionsWithoutDevctx: sessionsWithoutDevctx.length,
+    adoptionRate: sessions.length > 0 
+      ? Number(((sessionsWithDevctx.length / sessions.length) * 100).toFixed(1))
+      : 0,
+    
+    nonTrivial: {
+      total: nonTrivialSessions.length,
+      withDevctx: nonTrivialWithDevctx.length,
+      adoptionRate: nonTrivialSessions.length > 0
+        ? Number(((nonTrivialWithDevctx.length / nonTrivialSessions.length) * 100).toFixed(1))
+        : 0,
+    },
+    
+    byComplexity: Object.fromEntries(
+      Object.entries(byComplexity).map(([level, stats]) => [
+        level,
+        {
+          ...stats,
+          adoptionRate: stats.total > 0 
+            ? Number(((stats.withDevctx / stats.total) * 100).toFixed(1))
+            : 0,
+        },
+      ])
+    ),
+    
+    toolUsageCount,
+    
+    avgToolsPerSession: sessionsWithDevctx.length > 0
+      ? Number((sessionsWithDevctx.reduce((sum, s) => sum + s.devctxTools.size, 0) / sessionsWithDevctx.length).toFixed(1))
+      : 0,
+    
+    avgTokenSavingsWhenUsed: sessionsWithDevctx.length > 0
+      ? Number((sessionsWithDevctx.reduce((sum, s) => sum + s.totalSavedTokens, 0) / sessionsWithDevctx.length).toFixed(0))
+      : 0,
+  };
+};
+
+export const formatAdoptionReport = (stats) => {
+  const lines = [];
+  
+  lines.push('');
+  lines.push('Adoption Analysis (Inferred from Tool Usage)');
+  lines.push('');
+  lines.push(`Total sessions:        ${stats.totalSessions}`);
+  lines.push(`Sessions with devctx:  ${stats.sessionsWithDevctx} (${stats.adoptionRate}%)`);
+  lines.push(`Sessions without:      ${stats.sessionsWithoutDevctx} (${100 - stats.adoptionRate}%)`);
+  lines.push('');
+  
+  lines.push('Non-Trivial Tasks Only:');
+  lines.push(`Total:                 ${stats.nonTrivial.total}`);
+  lines.push(`With devctx:           ${stats.nonTrivial.withDevctx} (${stats.nonTrivial.adoptionRate}%)`);
+  lines.push(`Without devctx:        ${stats.nonTrivial.total - stats.nonTrivial.withDevctx} (${100 - stats.nonTrivial.adoptionRate}%)`);
+  lines.push('');
+  
+  lines.push('By Inferred Complexity:');
+  for (const [level, data] of Object.entries(stats.byComplexity)) {
+    if (data.total === 0) continue;
+    lines.push(`- ${level.padEnd(10)} ${data.withDevctx}/${data.total} (${data.adoptionRate}%)`);
+  }
+  lines.push('');
+  
+  if (stats.sessionsWithDevctx > 0) {
+    lines.push('When devctx IS used:');
+    lines.push(`Avg tools/session:     ${stats.avgToolsPerSession}`);
+    lines.push(`Avg token savings:     ${stats.avgTokenSavingsWhenUsed.toLocaleString()} tokens`);
+    lines.push('');
+  }
+  
+  lines.push('Top Tools Used:');
+  const sortedTools = Object.entries(stats.toolUsageCount)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5);
+  for (const [tool, count] of sortedTools) {
+    lines.push(`- ${tool.padEnd(20)} ${count} sessions`);
+  }
+  lines.push('');
+  
+  lines.push('Limitations:');
+  lines.push('- Complexity inferred from operation count (not actual task complexity)');
+  lines.push('- Can only measure when devctx IS used (tool calls visible)');
+  lines.push('- Cannot measure feedback shown or forcing prompts (requires agent cooperation)');
+  lines.push('- Sessions without devctx may be simple tasks (not adoption failures)');
+  lines.push('');
+  
+  return lines.join('\n');
+};