smart-context-mcp 1.5.0 → 1.6.0

package/README.md

@@ -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,41 @@ 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:**
@@ -167,11 +210,17 @@ Use devctx: smart_turn(start) → smart_context → smart_turn(end)
 - ✅ 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
 
@@ -392,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
 
@@ -403,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.5.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,9 +29,11 @@
     "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-adoption-metrics.js"
@@ -55,6 +59,8 @@
     "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",
@@ -62,7 +68,8 @@
     "eval:report": "node ./evals/report.js",
     "report:metrics": "node ./scripts/report-metrics.js",
     "report:workflows": "node ./scripts/report-workflow-metrics.js",
-    "report:adoption": "node ./scripts/report-adoption-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-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 () => {

package/scripts/report-workflow-metrics.js

@@ -116,14 +116,31 @@ const printSummary = (summary) => {
   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 totalOverhead = summary.reduce((sum, s) => sum + (s.total_overhead_tokens || 0), 0);
+  const totalNetSaved = summary.reduce((sum, s) => sum + (s.total_net_saved_tokens || 0), 0);
+  const totalNetCoverage = summary.reduce(
+    (sum, s) => sum + (s.netMetricsCoverage?.coveredWorkflows ?? s.net_metrics_count ?? 0),
+    0,
+  );
   const totalBaseline = summary.reduce((sum, s) => sum + s.total_baseline_tokens, 0);
+  const totalSavedPct = totalRaw > 0 ? ((totalSaved / totalRaw) * 100).toFixed(2) : '0.00';
+  const totalNetSavedPct = totalRaw > 0 ? ((totalNetSaved / totalRaw) * 100).toFixed(2) : '0.00';
+  const baselineSavingsPct = totalBaseline > 0
+    ? (((totalBaseline - totalCompressed) / totalBaseline) * 100).toFixed(2)
+    : '0.00';
 
   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 Saved Tokens: ${formatNumber(totalSaved)} (${totalSavedPct}%)`);
+  if (totalNetCoverage > 0) {
+    console.log(`Total Overhead Tokens: ${formatNumber(totalOverhead)}`);
+    console.log(
+      `Total Net Saved Tokens${totalNetCoverage < totalWorkflows ? ` (${formatNumber(totalNetCoverage)}/${formatNumber(totalWorkflows)} workflows)` : ''}: ${formatNumber(totalNetSaved)} (${totalNetSavedPct}%)`,
+    );
+  }
   console.log(`Total Baseline Tokens: ${formatNumber(totalBaseline)}`);
-  console.log(`Savings vs Baseline: ${formatNumber(totalBaseline - totalCompressed)} (${(((totalBaseline - totalCompressed) / totalBaseline) * 100).toFixed(2)}%)`);
+  console.log(`Savings vs Baseline: ${formatNumber(totalBaseline - totalCompressed)} (${baselineSavingsPct}%)`);
   console.log('');
   console.log('By Workflow Type:');
   console.log('─'.repeat(120));
@@ -169,6 +186,13 @@ const printSummary = (summary) => {
     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}%)`);
+    const coveredWorkflows = s.netMetricsCoverage?.coveredWorkflows ?? s.net_metrics_count ?? 0;
+    if (coveredWorkflows > 0) {
+      console.log(`  Total Overhead Tokens: ${formatNumber(s.total_overhead_tokens || 0)}`);
+      console.log(
+        `  Total Net Saved Tokens${coveredWorkflows < s.count ? ` (${formatNumber(coveredWorkflows)}/${formatNumber(s.count)} workflows)` : ''}: ${formatNumber(s.total_net_saved_tokens || 0)}`,
+      );
+    }
     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('');
@@ -205,6 +229,15 @@ const printWorkflows = (workflows) => {
       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}%)`);
+      if (w.overheadTokens !== undefined) {
+        console.log(`  Overhead Tokens: ${formatNumber(w.overheadTokens)}`);
+      }
+      if (w.netSavedTokens !== undefined) {
+        console.log(`  Net Saved Tokens: ${formatNumber(w.netSavedTokens)}`);
+      }
+      if (w.netMetricsCoverage?.available === false) {
+        console.log('  Net Metrics Coverage: unavailable');
+      }
       console.log(`  Baseline Tokens: ${formatNumber(w.baseline_tokens)}`);
       console.log(`  Savings vs Baseline: ${formatNumber(w.baseline_tokens - w.compressed_tokens)} (${w.vs_baseline_pct}%)`);
     }