smart-context-mcp 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # smart-context-mcp
 
-MCP server that reduces AI agent token usage by 90% with intelligent context compression.
+MCP server that reduces AI agent token usage by up to 90% with intelligent context compression (measured on this project).
 
 [![npm version](https://badge.fury.io/js/smart-context-mcp.svg)](https://www.npmjs.com/package/smart-context-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -14,6 +14,14 @@ npx smart-context-init --target . --clients cursor
 ```
 Restart Cursor. Done.
 
+Optional assisted mode for long tasks:
+```bash
+./.devctx/bin/cursor-devctx task --prompt "your task" -- <agent-command> [args...]
+./.devctx/bin/cursor-devctx implement --prompt "implement the auth guard" -- <agent-command> [args...]
+./.devctx/bin/cursor-devctx review --prompt "review the latest diff" -- <agent-command> [args...]
+./.devctx/bin/cursor-devctx doctor
+```
+
 ### Codex CLI
 ```bash
 npm install -g smart-context-mcp
@@ -44,6 +52,62 @@ Restart your AI client. Done.
 
 ---
 
+## `1.6.0` Task Runner
+
+`1.6.0` adds `smart-context-task`, a workflow-oriented CLI on top of the raw MCP tools.
+
+Use it when you want a more repeatable path than “agent reads rules and hopefully picks the right flow”.
+
+```bash
+smart-context-task task --prompt "inspect the auth flow and continue the bugfix"
+smart-context-task implement --prompt "add a token guard to loginHandler"
+smart-context-task continue --session-id my-session-id
+smart-context-task review --prompt "review the latest diff"
+smart-context-task doctor
+```
+
+The runner now covers:
+
+- `task`
+- `implement`
+- `continue`
+- `resume`
+- `review`
+- `debug`
+- `refactor`
+- `test`
+- `doctor`
+- `status`
+- `checkpoint`
+- `cleanup`
+
+For Cursor projects, `smart-context-init` also generates `./.devctx/bin/cursor-devctx`, which routes through the same runner/policy stack.
+
+See [Task Runner Workflows](../../docs/task-runner.md) for the full behavior and command guidance.
+
+---
+
+## 📊 Real Metrics
+
+**Production use on this project:**
+- ~7M tokens → ~800K tokens (approximately 89% reduction)
+- 1,500+ operations tracked
+- Compression ratios: 3x to 46x
+
+**Workflow savings:**
+- Debugging: ~85-90% reduction
+- Code Review: ~85-90% reduction
+- Refactoring: ~85-90% reduction
+- Testing: ~85-90% reduction
+- Architecture: ~85-90% reduction
+
+**Real adoption:**
+- Approximately 70-75% of complex tasks use devctx
+- Top tools: `smart_read` (850+), `smart_search` (280+), `smart_shell` (220+)
+- Non-usage: task too simple, no index built, native tools preferred
+
+---
+
 ## 🚀 How to Invoke the MCP
 
 The MCP doesn't intercept prompts automatically. **You need to tell the agent to use it.**
@@ -98,6 +162,36 @@ The agent *should* use devctx automatically for complex tasks because:
 
 ---
 
+## 🚨 Agent Ignored devctx? → Paste This Next
+
+<table>
+<tr>
+<td width="100%" bgcolor="#FFF3CD">
+
+### 📋 Official Prompt (Copy & Paste)
+
+```
+Use smart-context-mcp for this task.
+Start with smart_turn(start), then use smart_context or smart_search before reading full files.
+End with smart_turn(end) if you make progress.
+```
+
+### ⚡ Ultra-Short
+
+```
+Use devctx: smart_turn(start) → smart_context → smart_turn(end)
+```
+
+</td>
+</tr>
+</table>
+
+**When:** Agent read large files with `Read`, used `Grep` repeatedly, or no devctx tools in complex task.
+
+**Why:** Task seemed simple, no index built, native tools appeared more direct, or rules weren't strong enough.
+
+---
+
 ## How it Works in Practice
 
 **The reality:** This MCP does not intercept prompts automatically. Here's the actual flow:
@@ -116,11 +210,17 @@ The agent *should* use devctx automatically for complex tasks because:
 - ✅ Rules **guide** the agent (not enforce)
 - ✅ Agent can use built-in tools when appropriate
 - ✅ Token savings: 85-90% on complex tasks
+- ✅ Reports can show both gross savings and net savings after context overhead
+- ✅ Workflow JSON/reporting now exposes net-metrics coverage, so historical rows without persisted overhead are explicit
+- ✅ `smart_metrics` now exposes measured orchestration-quality signals from `smart_turn` (continuity recovery, blocked-state remediation coverage, context-refresh signals)
+- ✅ If `.devctx/state.sqlite` is tracked or staged, runtime SQLite mutations pause across checkpoints, workflow tracking, hook state, and pattern learning
 
 Check actual usage:
 - **Real-time feedback** - Enabled by default (disable with `export DEVCTX_SHOW_USAGE=false`)
 - `npm run report:metrics` - Tool-level savings + adoption analysis
 - `npm run report:workflows` - Workflow-level savings (requires `DEVCTX_WORKFLOW_TRACKING=true`)
+- `npm run benchmark:orchestration` - Repeatable orchestration regression suite for continuity, refresh, blocked-state remediation, and checkpoint quality
+- `npm run benchmark:orchestration:release` - Same suite with a checked-in release baseline, used by CI and `prepublishOnly`
 
 ## What it does
 
@@ -341,6 +441,23 @@ Maintain task checkpoint:
 ```
 
 Stores compressed task state (~100 tokens: goal, status, decisions, blockers), not full conversation. Supports both flat and nested parameter formats.
+When git hygiene or SQLite storage health affects persisted state, responses expose `mutationSafety`, `repoSafety`, `degradedMode`, and `storageHealth` so clients can remediate consistently.
+
+### smart_doctor
+
+Run a single operational health check across repo hygiene, SQLite state, compaction hygiene, and legacy cleanup:
+
+```javascript
+smart_doctor({})
+smart_doctor({ verifyIntegrity: false })
+```
+
+CLI:
+
+```bash
+smart-context-doctor --json
+smart-context-doctor --no-integrity
+```
 
 ### smart_status
 
@@ -352,6 +469,17 @@ Display current session context:
 ```
 
 Shows goal, status, recent decisions, touched files, and progress. Updates automatically with each MCP operation.
+When repo safety or SQLite health blocks normal state access, `smart_status` still exposes the same safety contract plus `storageHealth`.
+
+### SQLite Recovery
+
+If `.devctx/state.sqlite` is unhealthy, use the surfaced `storageHealth.issue`:
+
+- `missing`: initialize local state with a persisted action
+- `oversized`: run `smart_summary compact`
+- `locked`: stop competing devctx writers, then retry
+- `corrupted`: back up and remove the file so devctx can recreate it
+- broader inspection: run `smart_doctor` / `smart-context-doctor`
 
 ### smart_edit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.4.0",
+  "version": "1.6.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",
@@ -14,9 +14,11 @@
   },
   "bin": {
     "smart-context-headless": "scripts/headless-wrapper.js",
+    "smart-context-task": "scripts/task-runner.js",
     "smart-context-server": "scripts/devctx-server.js",
     "smart-context-init": "scripts/init-clients.js",
     "smart-context-report": "scripts/report-metrics.js",
+    "smart-context-doctor": "scripts/doctor-state.js",
     "smart-context-protect": "scripts/check-repo-safety.js"
   },
   "exports": {
@@ -27,11 +29,14 @@
     "src/",
     "scripts/claude-hook.js",
     "scripts/check-repo-safety.js",
+    "scripts/doctor-state.js",
     "scripts/devctx-server.js",
     "scripts/headless-wrapper.js",
     "scripts/init-clients.js",
+    "scripts/task-runner.js",
     "scripts/report-metrics.js",
-    "scripts/report-workflow-metrics.js"
+    "scripts/report-workflow-metrics.js",
+    "scripts/report-adoption-metrics.js"
   ],
   "engines": {
     "node": ">=18"
@@ -54,13 +59,17 @@
     "test": "node --test --test-concurrency=1 ./tests/*.test.js",
     "verify": "node ./scripts/verify-features-direct.js",
     "benchmark": "node ./scripts/run-benchmark.js",
+    "benchmark:orchestration": "node ./evals/orchestration-benchmark.js",
+    "benchmark:orchestration:release": "node ./evals/orchestration-benchmark.js --baseline=./evals/orchestration-release-baseline.json",
     "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:workflows": "node ./scripts/report-workflow-metrics.js"
+    "report:workflows": "node ./scripts/report-workflow-metrics.js",
+    "report:adoption": "node ./scripts/report-adoption-metrics.js",
+    "prepublishOnly": "npm test && npm run benchmark:orchestration:release"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.0",

package/scripts/doctor-state.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { smartDoctor } from '../src/tools/smart-doctor.js';
+import { setProjectRoot } from '../src/utils/runtime-config.js';
+
+const writeStdout = (text) => {
+  fs.writeSync(process.stdout.fd, text);
+};
+
+const writeStderr = (text) => {
+  fs.writeSync(process.stderr.fd, text);
+};
+
+const parseArgs = (argv) => {
+  const options = {
+    projectRoot: process.cwd(),
+    json: false,
+    verifyIntegrity: true,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === '--project-root') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('--')) {
+        throw new Error('Missing value for --project-root');
+      }
+      options.projectRoot = path.resolve(next);
+      index += 1;
+      continue;
+    }
+
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (token === '--no-integrity') {
+      options.verifyIntegrity = false;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+};
+
+const printHuman = (result) => {
+  const writer = result.overall === 'error' ? writeStderr : writeStdout;
+  writer(`devctx doctor: ${result.overall}\n`);
+  writer(`${result.message}\n`);
+
+  for (const check of result.checks ?? []) {
+    writer(`\n[${check.status}] ${check.id}: ${check.message}\n`);
+    for (const action of check.recommendedActions ?? []) {
+      writer(`- ${action}\n`);
+    }
+  }
+};
+
+const main = async () => {
+  const options = parseArgs(process.argv.slice(2));
+  setProjectRoot(options.projectRoot);
+
+  const result = await smartDoctor({
+    verifyIntegrity: options.verifyIntegrity,
+  });
+
+  if (options.json) {
+    const output = `${JSON.stringify(result, null, 2)}\n`;
+    if (result.overall === 'error') {
+      writeStderr(output);
+    } else {
+      writeStdout(output);
+    }
+  } else {
+    printHuman(result);
+  }
+
+  process.exitCode = result.overall === 'error' ? 1 : 0;
+};
+
+main().catch((error) => {
+  writeStderr(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/scripts/init-clients.js

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CLIENT_CONTRACT_RULE_LINES } from '../src/client-contract.js';
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const scriptsDir = path.dirname(currentFilePath);
@@ -164,6 +165,35 @@ const updateCursorConfig = (targetDir, serverConfig, dryRun) => {
   writeFile(filePath, `${JSON.stringify(current, null, 2)}\n`, dryRun);
 };
 
+const buildCursorAssistedLauncher = (targetDir) => {
+  const runnerScript = normalizeCommandPath(path.relative(targetDir, path.join(devctxDir, 'scripts', 'task-runner.js')));
+  return `#!/bin/sh
+set -eu
+
+script_dir="$(CDPATH= cd -- "$(dirname "$0")" && pwd)"
+project_root="$(CDPATH= cd -- "$script_dir/../.." && pwd)"
+
+export DEVCTX_PROJECT_ROOT="$project_root"
+
+if [ "$#" -gt 0 ] && [ "\${1#-}" = "$1" ]; then
+  subcommand="$1"
+  shift
+  exec "${process.execPath}" "$project_root/${runnerScript}" "$subcommand" --client cursor "$@"
+fi
+
+exec "${process.execPath}" "$project_root/${runnerScript}" task --client cursor "$@"
+`;
+};
+
+const updateCursorAssistedLauncher = (targetDir, dryRun) => {
+  const filePath = path.join(targetDir, '.devctx', 'bin', 'cursor-devctx');
+  writeFile(filePath, buildCursorAssistedLauncher(targetDir), dryRun);
+
+  if (!dryRun) {
+    fs.chmodSync(filePath, 0o755);
+  }
+};
+
 const updateClaudeConfig = (targetDir, serverConfig, dryRun) => {
   const filePath = path.join(targetDir, '.mcp.json');
   const current = readJson(filePath, { mcpServers: {} });
@@ -375,15 +405,25 @@ const updatePreCommitHook = (targetDir, dryRun) => {
 // Agent rules — instruct agents to prefer devctx tools over built-in ones
 // ---------------------------------------------------------------------------
 
-const agentRuleBody = `**First time in project?** Run build_index to enable search/context quality.
+const agentRuleBody = `**First time in project?** Run build_index(incremental=true) 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
+- smart_turn(start, userPrompt, ensureSession=true) before multi-step work
+- smart_context(...) or smart_search(intent=...) to build context cheaply
+- smart_read(outline|signatures|symbol) before full reads
+- smart_shell instead of Shell for safe diagnostics
+- smart_turn(end, event=milestone) after meaningful progress
+
+If devctx MCP is installed and enabled, default to devctx on every non-trivial multi-file or multi-step task. Skip it only for genuinely trivial work, and then state why it was skipped.
+
+Client contract:
+- ${CLIENT_CONTRACT_RULE_LINES.join('\n- ')}
 
-For non-trivial tasks: smart_turn(start) → [work with devctx tools] → smart_turn(end)
+Cursor assisted mode:
+- For long or continuity-sensitive tasks, prefer the local launcher \`./.devctx/bin/cursor-devctx\`
+- Usage: \`./.devctx/bin/cursor-devctx task --prompt "your task" -- <agent-command> [args...]\`
+- Specialized flows: \`review\`, \`debug\`, \`refactor\`, \`test\`, \`doctor\`, \`status\`, \`checkpoint\`, \`cleanup\`
+- This launcher wraps the prompt with smart_turn(start/end) orchestration and the shared operational contract
 
 Reading cascade: outline → signatures → symbol → full (last resort)
 
@@ -393,7 +433,7 @@ Detailed workflows: .cursor/rules/profiles-compact/ (debugging, code-review, ref
 
 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)"`;
+**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, userPrompt, ensureSession=true) → smart_context/smart_search → smart_read → smart_turn(end, event=milestone)"`;
 
 const cursorRuleContent = `---
 description: Prefer devctx MCP tools for non-trivial tasks
@@ -515,6 +555,7 @@ const main = () => {
   if (clientSet.has('cursor')) {
     updateCursorConfig(targetDir, serverConfig, options.dryRun);
     updateCursorRule(targetDir, options.dryRun);
+    updateCursorAssistedLauncher(targetDir, options.dryRun);
   }
 
   if (clientSet.has('codex')) {

package/scripts/report-adoption-metrics.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * Report adoption metrics - measures real MCP usage in non-trivial tasks
+ * 
+ * Usage:
+ *   npm run report:adoption
+ *   npm run report:adoption -- --days 7
+ *   npm run report:adoption -- --json
+ */
+
+import { withStateDb } from '../src/storage/sqlite.js';
+import { WORKFLOW_DEFINITIONS } from '../src/workflow-tracker.js';
+
+const parseArgs = (argv) => {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--days' && argv[i + 1]) {
+      args.days = parseInt(argv[i + 1], 10);
+      i++;
+    } else if (argv[i] === '--json') {
+      args.json = true;
+    }
+  }
+  return args;
+};
+
+const formatPct = (value) => `${value.toFixed(1)}%`;
+const formatNumber = (value) => new Intl.NumberFormat('en-US').format(value);
+
+/**
+ * Classify if a session represents a non-trivial task
+ */
+const isNonTrivialTask = (sessionEvents, metricsEvents) => {
+  // Criteria 1: Multiple operations (≥5)
+  if (sessionEvents.length + metricsEvents.length >= 5) return true;
+
+  // Criteria 2: Large file reads (any file >500 lines)
+  const hasLargeFileRead = metricsEvents.some(
+    (m) => m.tool === 'Read' && m.raw_tokens > 1500 // ~500 lines
+  );
+  if (hasLargeFileRead) return true;
+
+  // Criteria 3: Multiple file reads (≥3)
+  const fileReads = metricsEvents.filter((m) => m.tool === 'Read' || m.tool === 'smart_read');
+  if (fileReads.length >= 3) return true;
+
+  // Criteria 4: Repeated searches (≥2)
+  const searches = metricsEvents.filter((m) => m.tool === 'Grep' || m.tool === 'smart_search');
+  if (searches.length >= 2) return true;
+
+  // Criteria 5: Workflow classification
+  const devctxTools = metricsEvents.filter((m) =>
+    ['smart_turn', 'smart_context', 'smart_search', 'smart_read', 'smart_shell'].includes(m.tool)
+  );
+  if (devctxTools.length > 0) return true;
+
+  return false;
+};
+
+/**
+ * Check if session used devctx tools
+ */
+const usedDevctx = (metricsEvents) => {
+  const devctxTools = ['smart_turn', 'smart_context', 'smart_search', 'smart_read', 'smart_shell', 'smart_read_batch'];
+  return metricsEvents.some((m) => devctxTools.includes(m.tool));
+};
+
+/**
+ * Calculate adoption metrics
+ */
+const calculateAdoptionMetrics = (days = 30) => {
+  return withStateDb((db) => {
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+
+    // Get all sessions since cutoff
+    const sessions = db
+      .prepare(
+        `
+      SELECT session_id, snapshot_json, created_at
+      FROM sessions
+      WHERE created_at >= ?
+      ORDER BY created_at DESC
+    `
+      )
+      .all(cutoff);
+
+    const results = {
+      totalSessions: sessions.length,
+      nonTrivialTasks: 0,
+      tasksWithDevctx: 0,
+      adoptionRate: 0,
+      byWorkflow: {},
+      toolUsage: {},
+    };
+
+    // Initialize workflow stats
+    Object.keys(WORKFLOW_DEFINITIONS).forEach((type) => {
+      results.byWorkflow[type] = {
+        total: 0,
+        withDevctx: 0,
+        adoptionRate: 0,
+      };
+    });
+
+    // Analyze each session
+    sessions.forEach((session) => {
+      const snapshot = JSON.parse(session.snapshot_json || '{}');
+      const sessionId = session.session_id;
+
+      // Get events for this session
+      const sessionEvents = db
+        .prepare('SELECT * FROM session_events WHERE session_id = ?')
+        .all(sessionId);
+
+      const metricsEvents = db
+        .prepare('SELECT * FROM metrics_events WHERE session_id = ?')
+        .all(sessionId);
+
+      // Check if non-trivial
+      if (!isNonTrivialTask(sessionEvents, metricsEvents)) {
+        return;
+      }
+
+      results.nonTrivialTasks++;
+
+      // Check if used devctx
+      const hasDevctx = usedDevctx(metricsEvents);
+      if (hasDevctx) {
+        results.tasksWithDevctx++;
+      }
+
+      // Track tool usage
+      metricsEvents.forEach((m) => {
+        results.toolUsage[m.tool] = (results.toolUsage[m.tool] || 0) + 1;
+      });
+
+      // Classify by workflow if possible
+      const goal = snapshot.goal || '';
+      let workflowType = null;
+
+      for (const [type, def] of Object.entries(WORKFLOW_DEFINITIONS)) {
+        if (def.pattern.test(goal)) {
+          workflowType = type;
+          break;
+        }
+      }
+
+      if (workflowType) {
+        results.byWorkflow[workflowType].total++;
+        if (hasDevctx) {
+          results.byWorkflow[workflowType].withDevctx++;
+        }
+      }
+    });
+
+    // Calculate rates
+    if (results.nonTrivialTasks > 0) {
+      results.adoptionRate = (results.tasksWithDevctx / results.nonTrivialTasks) * 100;
+    }
+
+    Object.keys(results.byWorkflow).forEach((type) => {
+      const stats = results.byWorkflow[type];
+      if (stats.total > 0) {
+        stats.adoptionRate = (stats.withDevctx / stats.total) * 100;
+      }
+    });
+
+    return results;
+  });
+};
+
+/**
+ * Format and print report
+ */
+const printReport = (metrics, days) => {
+  console.log(`\nAdoption Metrics (Last ${days} Days)`);
+  console.log('='.repeat(50));
+  console.log();
+
+  console.log(`Total Sessions: ${formatNumber(metrics.totalSessions)}`);
+  console.log(`Non-Trivial Tasks: ${formatNumber(metrics.nonTrivialTasks)}`);
+  console.log(`Tasks with devctx: ${formatNumber(metrics.tasksWithDevctx)}`);
+  console.log();
+
+  console.log(`Overall Adoption: ${formatPct(metrics.adoptionRate)}`);
+  console.log();
+
+  console.log('By Workflow:');
+  Object.entries(metrics.byWorkflow)
+    .filter(([, stats]) => stats.total > 0)
+    .sort((a, b) => b[1].adoptionRate - a[1].adoptionRate)
+    .forEach(([type, stats]) => {
+      const def = WORKFLOW_DEFINITIONS[type];
+      console.log(
+        `  ${def.name.padEnd(25)} ${formatPct(stats.adoptionRate).padStart(7)} (${stats.withDevctx}/${stats.total})`
+      );
+    });
+  console.log();
+
+  console.log('Top devctx Tools:');
+  const devctxTools = ['smart_turn', 'smart_context', 'smart_search', 'smart_read', 'smart_shell'];
+  Object.entries(metrics.toolUsage)
+    .filter(([tool]) => devctxTools.includes(tool))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .forEach(([tool, count]) => {
+      console.log(`  ${tool.padEnd(20)} ${formatNumber(count)} uses`);
+    });
+  console.log();
+};
+
+// Main
+const args = parseArgs(process.argv);
+const days = args.days || 30;
+
+try {
+  const metrics = calculateAdoptionMetrics(days);
+
+  if (args.json) {
+    console.log(JSON.stringify(metrics, null, 2));
+  } else {
+    printReport(metrics, days);
+  }
+} catch (error) {
+  console.error('Error calculating adoption metrics:', error.message);
+  process.exit(1);
+}

package/scripts/report-metrics.js

@@ -3,6 +3,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';
+import { formatProductQualityReport } from '../src/analytics/product-quality.js';
 
 const requireValue = (argv, index, flag) => {
   const value = argv[index + 1];
@@ -60,6 +61,8 @@ export const createReport = async (options) => {
     toolFilter: options.tool,
     invalidLines: result.invalidLines,
     summary: result.summary,
+    adoption: result.adoption,
+    productQuality: result.productQuality,
   };
 };
 
@@ -73,6 +76,10 @@ const printHuman = (report) => {
   console.log(`Raw tokens:   ${formatNumber(report.summary.rawTokens)}`);
   console.log(`Final tokens: ${formatNumber(report.summary.compressedTokens)}`);
   console.log(`Saved tokens: ${formatNumber(report.summary.savedTokens)} (${report.summary.savingsPct}%)`);
+  console.log(`Net saved:    ${formatNumber(report.summary.netSavedTokens)} (${report.summary.netSavingsPct}%)`);
+  if (report.summary.overheadTokens > 0) {
+    console.log(`Overhead:     ${formatNumber(report.summary.overheadTokens)} (${report.summary.overheadPctOfRaw}% of raw)`);
+  }
   if (report.invalidLines.length > 0) {
     console.log(`Invalid JSONL: ${report.invalidLines.join(', ')}`);
   }
@@ -86,13 +93,17 @@ const printHuman = (report) => {
 
   for (const tool of report.summary.tools) {
     console.log(
-      `  ${tool.tool.padEnd(14)} count=${formatNumber(tool.count)} raw=${formatNumber(tool.rawTokens)} final=${formatNumber(tool.compressedTokens)} saved=${formatNumber(tool.savedTokens)} (${tool.savingsPct}%)`
+      `  ${tool.tool.padEnd(14)} count=${formatNumber(tool.count)} raw=${formatNumber(tool.rawTokens)} final=${formatNumber(tool.compressedTokens)} saved=${formatNumber(tool.savedTokens)} (${tool.savingsPct}%) net=${formatNumber(tool.netSavedTokens)} (${tool.netSavingsPct}%)`
     );
   }
   
   if (report.adoption) {
     console.log(formatAdoptionReport(report.adoption));
   }
+
+  if (report.productQuality?.turnsMeasured > 0) {
+    console.log(formatProductQualityReport(report.productQuality));
+  }
 };
 
 export const main = async () => {