smart-context-mcp 1.4.0 → 1.6.0

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}%)`);
     }

package/scripts/task-runner.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import { runTaskRunner } from '../src/task-runner.js';
+
+const requireValue = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (!value || value === '--') {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+};
+
+const parseListValue = (raw) =>
+  raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+const parseArgs = (argv) => {
+  const subcommand = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'task';
+  const rest = argv[0] && !argv[0].startsWith('--') ? argv.slice(1) : argv;
+  const options = {
+    commandName: subcommand,
+    client: 'generic',
+    prompt: '',
+    sessionId: undefined,
+    event: undefined,
+    stdinPrompt: false,
+    dryRun: false,
+    json: false,
+    streamOutput: true,
+    allowDegraded: false,
+    verifyIntegrity: true,
+    format: 'compact',
+    maxItems: 10,
+    cleanupMode: 'compact',
+    apply: false,
+    retentionDays: 30,
+    keepLatestEventsPerSession: 20,
+    keepLatestMetrics: 1000,
+    vacuum: false,
+    command: '',
+    args: [],
+    update: {},
+  };
+
+  const listFields = new Map([
+    ['--completed', 'completed'],
+    ['--decisions', 'decisions'],
+    ['--blockers', 'blockers'],
+    ['--touched-files', 'touchedFiles'],
+    ['--pinned-context', 'pinnedContext'],
+    ['--unresolved-questions', 'unresolvedQuestions'],
+  ]);
+
+  let commandIndex = rest.indexOf('--');
+  const head = commandIndex === -1 ? rest : rest.slice(0, commandIndex);
+
+  for (let index = 0; index < head.length; index += 1) {
+    const token = head[index];
+
+    if (token === '--client') {
+      options.client = requireValue(head, index, '--client');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--prompt') {
+      options.prompt = requireValue(head, index, '--prompt');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--session-id') {
+      options.sessionId = requireValue(head, index, '--session-id');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--event') {
+      options.event = requireValue(head, index, '--event');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--stdin-prompt') {
+      options.stdinPrompt = true;
+      continue;
+    }
+
+    if (token === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (token === '--quiet') {
+      options.streamOutput = false;
+      continue;
+    }
+
+    if (token === '--allow-degraded') {
+      options.allowDegraded = true;
+      continue;
+    }
+
+    if (token === '--no-integrity') {
+      options.verifyIntegrity = false;
+      continue;
+    }
+
+    if (token === '--format') {
+      options.format = requireValue(head, index, '--format');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--max-items') {
+      options.maxItems = Number(requireValue(head, index, '--max-items'));
+      index += 1;
+      continue;
+    }
+
+    if (token === '--cleanup-mode') {
+      options.cleanupMode = requireValue(head, index, '--cleanup-mode');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--apply') {
+      options.apply = true;
+      continue;
+    }
+
+    if (token === '--retention-days') {
+      options.retentionDays = Number(requireValue(head, index, '--retention-days'));
+      index += 1;
+      continue;
+    }
+
+    if (token === '--keep-latest-events') {
+      options.keepLatestEventsPerSession = Number(requireValue(head, index, '--keep-latest-events'));
+      index += 1;
+      continue;
+    }
+
+    if (token === '--keep-latest-metrics') {
+      options.keepLatestMetrics = Number(requireValue(head, index, '--keep-latest-metrics'));
+      index += 1;
+      continue;
+    }
+
+    if (token === '--vacuum') {
+      options.vacuum = true;
+      continue;
+    }
+
+    if (token === '--goal') {
+      options.update.goal = requireValue(head, index, '--goal');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--status') {
+      options.update.status = requireValue(head, index, '--status');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--current-focus') {
+      options.update.currentFocus = requireValue(head, index, '--current-focus');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--why-blocked') {
+      options.update.whyBlocked = requireValue(head, index, '--why-blocked');
+      index += 1;
+      continue;
+    }
+
+    if (token === '--next-step') {
+      options.update.nextStep = requireValue(head, index, '--next-step');
+      index += 1;
+      continue;
+    }
+
+    if (listFields.has(token)) {
+      const field = listFields.get(token);
+      options.update[field] = parseListValue(requireValue(head, index, token));
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (commandIndex !== -1) {
+    const commandParts = rest.slice(commandIndex + 1);
+    if (commandParts.length > 0) {
+      [options.command, ...options.args] = commandParts;
+    }
+  }
+
+  return options;
+};
+
+const main = async () => {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.json) {
+    options.streamOutput = false;
+  }
+
+  const result = await runTaskRunner(options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+
+  if (result?.blocked) {
+    process.exitCode = 2;
+    return;
+  }
+
+  if (typeof result?.exitCode === 'number' && result.exitCode !== 0) {
+    process.exitCode = result.exitCode;
+    return;
+  }
+
+  if (result?.overall === 'error') {
+    process.exitCode = 1;
+  }
+};
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/src/analytics/product-quality.js

@@ -0,0 +1,206 @@
+const roundPct = (value, total) =>
+  total > 0 ? Number(((value / total) * 100).toFixed(1)) : 0;
+
+export const PRODUCT_QUALITY_ANALYTICS_KIND = 'smart_turn_quality';
+export const TASK_RUNNER_QUALITY_ANALYTICS_KIND = 'task_runner_quality';
+
+const isProductQualityEntry = (entry) =>
+  entry?.tool === 'smart_turn'
+  && entry?.metadata?.analyticsKind === PRODUCT_QUALITY_ANALYTICS_KIND;
+
+const isTaskRunnerQualityEntry = (entry) =>
+  entry?.tool === 'task_runner'
+  && entry?.metadata?.analyticsKind === TASK_RUNNER_QUALITY_ANALYTICS_KIND;
+
+const analyzeTaskRunnerQuality = (entries = []) => {
+  const runnerEntries = entries.filter(isTaskRunnerQualityEntry);
+  const workflowEntries = runnerEntries.filter((entry) => entry.metadata?.isWorkflowCommand);
+  const specializedWorkflowEntries = workflowEntries.filter((entry) => entry.metadata?.specializedWorkflow);
+  const specializedExecutableEntries = specializedWorkflowEntries.filter((entry) => !entry.metadata?.blocked);
+  const blockedEntries = runnerEntries.filter((entry) => entry.metadata?.blocked);
+  const doctorEntries = runnerEntries.filter((entry) => entry.metadata?.doctorIssued);
+  const wrappedEntries = workflowEntries.filter((entry) => entry.metadata?.usedWrapper);
+  const workflowPolicyEntries = workflowEntries.filter((entry) => entry.metadata?.workflowPolicyMode);
+  const preflightEntries = specializedWorkflowEntries.filter((entry) => entry.metadata?.workflowPreflightTool);
+  const blockedWithDoctor = blockedEntries.filter((entry) => entry.metadata?.doctorIssued);
+  const checkpointEntries = runnerEntries.filter((entry) => entry.action === 'checkpoint');
+  const persistedCheckpointEntries = checkpointEntries.filter((entry) => entry.metadata?.checkpointPersisted);
+
+  const commandBreakdown = [...runnerEntries.reduce((acc, entry) => {
+    const key = entry.action ?? 'unknown';
+    const current = acc.get(key) ?? {
+      command: key,
+      count: 0,
+      blocked: 0,
+      doctorIssued: 0,
+      usedWrapper: 0,
+      preflighted: 0,
+    };
+    current.count += 1;
+    current.blocked += entry.metadata?.blocked ? 1 : 0;
+    current.doctorIssued += entry.metadata?.doctorIssued ? 1 : 0;
+    current.usedWrapper += entry.metadata?.usedWrapper ? 1 : 0;
+    current.preflighted += entry.metadata?.workflowPreflightTool ? 1 : 0;
+    acc.set(key, current);
+    return acc;
+  }, new Map()).values()].sort((a, b) => b.count - a.count || a.command.localeCompare(b.command));
+
+  return {
+    commandsMeasured: runnerEntries.length,
+    workflowCommands: workflowEntries.length,
+    specializedWorkflowCommands: specializedWorkflowEntries.length,
+    blockedCommands: blockedEntries.length,
+    doctorCommands: doctorEntries.length,
+    dryRunCommands: runnerEntries.filter((entry) => entry.metadata?.dryRun).length,
+    commandBreakdown,
+    workflowPolicy: {
+      coveredCommands: workflowPolicyEntries.length,
+      preflightedCommands: preflightEntries.length,
+      wrapperBackedCommands: wrappedEntries.length,
+      coveragePct: roundPct(workflowPolicyEntries.length, workflowEntries.length),
+      preflightCoveragePct: roundPct(preflightEntries.length, specializedWorkflowEntries.length),
+      wrapperCoveragePct: roundPct(wrappedEntries.length, workflowEntries.length),
+    },
+    blockedState: {
+      blockedCommands: blockedEntries.length,
+      blockedWithDoctor: blockedWithDoctor.length,
+      doctorCoveragePct: roundPct(blockedWithDoctor.length, blockedEntries.length),
+    },
+    checkpointing: {
+      commandsMeasured: checkpointEntries.length,
+      persistedCommands: persistedCheckpointEntries.length,
+      persistenceRatePct: roundPct(persistedCheckpointEntries.length, checkpointEntries.length),
+    },
+  };
+};
+
+export const analyzeProductQuality = (entries = []) => {
+  const qualityEntries = entries.filter(isProductQualityEntry);
+  const startEntries = qualityEntries.filter((entry) => entry.metadata?.phase === 'start');
+  const endEntries = qualityEntries.filter((entry) => entry.metadata?.phase === 'end');
+
+  const alignedStarts = startEntries.filter((entry) => entry.metadata?.continuityState === 'aligned').length;
+  const reusableStarts = startEntries.filter((entry) => entry.metadata?.shouldReuseContext).length;
+  const isolatedStarts = startEntries.filter((entry) => entry.metadata?.isolatedSession).length;
+  const ambiguousStarts = startEntries.filter((entry) => entry.metadata?.continuityState === 'ambiguous_resume').length;
+  const coldStarts = startEntries.filter((entry) => entry.metadata?.continuityState === 'cold_start').length;
+
+  const blockedTurns = qualityEntries.filter((entry) => entry.metadata?.mutationBlocked).length;
+  const blockedWithActions = qualityEntries.filter((entry) =>
+    entry.metadata?.mutationBlocked && Number(entry.metadata?.recommendedActionsCount ?? 0) > 0
+  ).length;
+
+  const refreshedStarts = startEntries.filter((entry) => entry.metadata?.refreshedContext).length;
+  const refreshedWithTopFiles = startEntries.filter((entry) => Number(entry.metadata?.refreshedTopFiles ?? 0) > 0).length;
+  const indexRefreshedStarts = startEntries.filter((entry) => entry.metadata?.indexRefreshed).length;
+
+  const persistedEnds = endEntries.filter((entry) => entry.metadata?.checkpointPersisted).length;
+  const skippedEnds = endEntries.filter((entry) => entry.metadata?.checkpointSkipped).length;
+  const blockedEnds = endEntries.filter((entry) => entry.metadata?.mutationBlocked).length;
+
+  return {
+    turnsMeasured: qualityEntries.length,
+    startsMeasured: startEntries.length,
+    endsMeasured: endEntries.length,
+    continuityRecovery: {
+      startsMeasured: startEntries.length,
+      alignedStarts,
+      reusableStarts,
+      isolatedStarts,
+      ambiguousStarts,
+      coldStarts,
+      alignmentRatePct: roundPct(alignedStarts, startEntries.length),
+      reusableRatePct: roundPct(reusableStarts, startEntries.length),
+    },
+    blockedState: {
+      turnsBlocked: blockedTurns,
+      blockedStarts: qualityEntries.filter((entry) => entry.metadata?.phase === 'start' && entry.metadata?.mutationBlocked).length,
+      blockedEnds,
+      blockedWithRecommendedActions: blockedWithActions,
+      remediationCoveragePct: roundPct(blockedWithActions, blockedTurns),
+    },
+    contextRefresh: {
+      refreshedStarts,
+      refreshedWithTopFiles,
+      indexRefreshedStarts,
+      topFileSignalRatePct: roundPct(refreshedWithTopFiles, refreshedStarts),
+    },
+    checkpointing: {
+      endsMeasured: endEntries.length,
+      persistedEnds,
+      skippedEnds,
+      blockedEnds,
+      persistenceRatePct: roundPct(persistedEnds, endEntries.length),
+    },
+    taskRunner: analyzeTaskRunnerQuality(entries),
+  };
+};
+
+export const formatProductQualityReport = (stats) => {
+  const hasSmartTurn = Number(stats?.turnsMeasured ?? 0) > 0;
+  const hasTaskRunner = Number(stats?.taskRunner?.commandsMeasured ?? 0) > 0;
+
+  if (!stats || (!hasSmartTurn && !hasTaskRunner)) {
+    return '';
+  }
+
+  const lines = [];
+  lines.push('');
+  lines.push('Product Quality Signals');
+  lines.push('');
+
+  if (hasSmartTurn) {
+    lines.push('smart_turn orchestration:');
+    lines.push(`Turns measured:        ${stats.turnsMeasured}`);
+    lines.push(`Start turns:           ${stats.startsMeasured}`);
+    lines.push(`End turns:             ${stats.endsMeasured}`);
+    lines.push('');
+    lines.push('Continuity Recovery:');
+    lines.push(`Aligned starts:        ${stats.continuityRecovery.alignedStarts}/${stats.continuityRecovery.startsMeasured} (${stats.continuityRecovery.alignmentRatePct}%)`);
+    lines.push(`Reusable starts:       ${stats.continuityRecovery.reusableStarts}/${stats.continuityRecovery.startsMeasured} (${stats.continuityRecovery.reusableRatePct}%)`);
+    lines.push(`Isolated starts:       ${stats.continuityRecovery.isolatedStarts}`);
+    lines.push(`Ambiguous resumes:     ${stats.continuityRecovery.ambiguousStarts}`);
+    lines.push('');
+    lines.push('Blocked-State Handling:');
+    lines.push(`Blocked turns:         ${stats.blockedState.turnsBlocked}`);
+    lines.push(`With remediation:      ${stats.blockedState.blockedWithRecommendedActions}/${stats.blockedState.turnsBlocked} (${stats.blockedState.remediationCoveragePct}%)`);
+    lines.push('');
+    lines.push('Context Refresh Signals:');
+    lines.push(`Refreshed starts:      ${stats.contextRefresh.refreshedStarts}`);
+    lines.push(`With top-file signal:  ${stats.contextRefresh.refreshedWithTopFiles}/${stats.contextRefresh.refreshedStarts} (${stats.contextRefresh.topFileSignalRatePct}%)`);
+    lines.push(`Index refreshes:       ${stats.contextRefresh.indexRefreshedStarts}`);
+    lines.push('');
+    lines.push('Checkpointing:');
+    lines.push(`Persisted ends:        ${stats.checkpointing.persistedEnds}/${stats.checkpointing.endsMeasured} (${stats.checkpointing.persistenceRatePct}%)`);
+    lines.push(`Skipped ends:          ${stats.checkpointing.skippedEnds}`);
+    lines.push(`Blocked ends:          ${stats.checkpointing.blockedEnds}`);
+    lines.push('');
+  }
+
+  if (hasTaskRunner) {
+    lines.push('task_runner workflows:');
+    lines.push(`Commands measured:     ${stats.taskRunner.commandsMeasured}`);
+    lines.push(`Workflow commands:     ${stats.taskRunner.workflowCommands}`);
+    lines.push(`Specialized commands:  ${stats.taskRunner.specializedWorkflowCommands}`);
+    lines.push(`Blocked commands:      ${stats.taskRunner.blockedCommands}`);
+    lines.push(`Doctor commands:       ${stats.taskRunner.doctorCommands}`);
+    lines.push('');
+    lines.push('Workflow Policy Coverage:');
+    lines.push(`Policy-backed:         ${stats.taskRunner.workflowPolicy.coveredCommands}/${stats.taskRunner.workflowCommands} (${stats.taskRunner.workflowPolicy.coveragePct}%)`);
+    lines.push(`Preflighted:           ${stats.taskRunner.workflowPolicy.preflightedCommands}/${stats.taskRunner.specializedWorkflowCommands} (${stats.taskRunner.workflowPolicy.preflightCoveragePct}%)`);
+    lines.push(`Wrapper-backed:        ${stats.taskRunner.workflowPolicy.wrapperBackedCommands}/${stats.taskRunner.workflowCommands} (${stats.taskRunner.workflowPolicy.wrapperCoveragePct}%)`);
+    lines.push('');
+    lines.push('Blocked-State Routing:');
+    lines.push(`Blocked with doctor:   ${stats.taskRunner.blockedState.blockedWithDoctor}/${stats.taskRunner.blockedState.blockedCommands} (${stats.taskRunner.blockedState.doctorCoveragePct}%)`);
+    lines.push('');
+    lines.push('Checkpoint Commands:');
+    lines.push(`Persisted checkpoints: ${stats.taskRunner.checkpointing.persistedCommands}/${stats.taskRunner.checkpointing.commandsMeasured} (${stats.taskRunner.checkpointing.persistenceRatePct}%)`);
+    lines.push('');
+  }
+
+  lines.push('Notes:');
+  lines.push('- These are measured orchestration signals, not direct answer-quality scores.');
+  lines.push('- Context refresh usefulness is proxied by whether refreshed turns surfaced top-file signals.');
+  lines.push('');
+  return lines.join('\n');
+};

package/src/client-contract.js

@@ -0,0 +1,153 @@
+const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+const truncate = (value, maxLength = 120) => {
+  const normalized = normalizeWhitespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  if (maxLength <= 3) {
+    return '';
+  }
+
+  return `${normalized.slice(0, maxLength - 3)}...`;
+};
+
+export const CLIENT_CONTRACT_RULE_LINES = [
+  'Treat smart_turn as the task entry point for non-trivial work.',
+  'If smart_turn returns mutationSafety.blocked = true, stop write-heavy work, surface blockedBy, and follow recommendedActions before retrying persisted steps.',
+  'If smart_turn or smart_doctor reports storageHealth.issue !== "ok", pause persisted context writes and remediate local state before continuing.',
+  'Use smart_doctor when repo safety or SQLite health is unhealthy or unclear.',
+  'Use workflow, continuity, recommendedPath, mutationSafety, and storageHealth as the current operational state for the task.',
+];
+
+export const buildMutationSafetyActionLines = (
+  mutationSafety,
+  {
+    prefix = 'fix',
+    maxLength = 110,
+    maxItems = 2,
+  } = {},
+) =>
+  (mutationSafety?.recommendedActions ?? [])
+    .slice(0, maxItems)
+    .map((action) => `${prefix}: ${truncate(action, maxLength)}`);
+
+export const buildRecommendedPathLines = (
+  recommendedPath,
+  {
+    includePath = true,
+    maxLength = 110,
+    nextToolsLabel = 'next tools',
+    pathLabel = 'path',
+  } = {},
+) => {
+  if (!recommendedPath) {
+    return [];
+  }
+
+  const lines = [];
+
+  if (Array.isArray(recommendedPath.nextTools) && recommendedPath.nextTools.length > 0) {
+    lines.push(`${nextToolsLabel}: ${recommendedPath.nextTools.slice(0, 3).join(' -> ')}`);
+  }
+
+  if (includePath && recommendedPath.steps?.[0]?.instruction) {
+    lines.push(`${pathLabel}: ${truncate(recommendedPath.steps[0].instruction, maxLength)}`);
+  }
+
+  return lines;
+};
+
+export const buildOperationalContextLines = (
+  result,
+  {
+    sessionStart = false,
+    maxLineLength = 110,
+    maxLines = 7,
+    maxChars = 420,
+  } = {},
+) => {
+  const lines = [];
+  const repoSafety = result?.repoSafety;
+  const mutationSafety = result?.mutationSafety;
+  const summary = result?.summary;
+  const continuityState = result?.continuity?.state;
+  const storageIssue = result?.storageHealth?.issue;
+
+  if (result?.found && summary) {
+    const label = sessionStart ? 'resume' : continuityState ?? 'resume';
+    lines.push(`devctx ${label}: session ${result.sessionId}`);
+
+    if (summary.goal) {
+      lines.push(`goal: ${truncate(summary.goal, maxLineLength)}`);
+    }
+
+    if (summary.currentFocus) {
+      lines.push(`focus: ${truncate(summary.currentFocus, maxLineLength)}`);
+    }
+
+    if (!mutationSafety?.blocked) {
+      lines.push(...buildRecommendedPathLines(result?.recommendedPath, {
+        includePath: true,
+        maxLength: maxLineLength,
+      }));
+    }
+
+    if (summary.nextStep) {
+      lines.push(`next: ${truncate(summary.nextStep, maxLineLength)}`);
+    }
+  } else if (continuityState === 'ambiguous_resume') {
+    lines.push('devctx: multiple persisted sessions matched this prompt.');
+    if (result?.recommendedSessionId) {
+      lines.push(`recommended session: ${result.recommendedSessionId}`);
+    }
+  } else if (result?.autoCreated && summary?.goal) {
+    lines.push(`devctx new task session: ${truncate(summary.goal, maxLineLength)}`);
+  }
+
+  if (result?.continuity?.reason) {
+    lines.push(`context status: ${truncate(result.continuity.reason, maxLineLength)}`);
+  }
+
+  if (mutationSafety?.blocked) {
+    const reasons = mutationSafety.blockedBy?.join(' and ') || 'blocked';
+    lines.push(`repo safety: ${mutationSafety.stateDbPath} is ${reasons}; context writes are blocked.`);
+    lines.push(...buildRecommendedPathLines(result?.recommendedPath, {
+      includePath: false,
+      maxLength: maxLineLength,
+    }));
+    lines.push(...buildMutationSafetyActionLines(mutationSafety, {
+      prefix: 'fix',
+      maxLength: maxLineLength,
+    }));
+  } else if (repoSafety?.isTracked || repoSafety?.isStaged) {
+    const reasons = [];
+    if (repoSafety.isTracked) {
+      reasons.push('tracked');
+    }
+    if (repoSafety.isStaged) {
+      reasons.push('staged');
+    }
+    lines.push(`repo safety: .devctx/state.sqlite is ${reasons.join(' and ')}; context writes are blocked.`);
+  }
+
+  if (storageIssue && storageIssue !== 'ok') {
+    lines.push(`storage health: ${storageIssue}`);
+    lines.push('doctor: run smart_doctor before retrying persisted context writes.');
+  }
+
+  if (result?.refreshedContext?.indexRefreshed) {
+    lines.push('context refresh: project index was refreshed for this prompt.');
+  }
+
+  if (result?.refreshedContext?.topFiles?.length > 0) {
+    lines.push(`files: ${result.refreshedContext.topFiles.map((item) => item.file).slice(0, 2).join(', ')}`);
+  }
+
+  if (result?.refreshedContext?.hints?.[0]) {
+    lines.push(`hint: ${truncate(result.refreshedContext.hints[0], maxLineLength)}`);
+  }
+
+  return lines.slice(0, maxLines).join('\n').slice(0, maxChars).trim() || null;
+};

package/src/context-patterns.js

@@ -1,3 +1,4 @@
+import { getRepoMutationSafety } from './repo-safety.js';
 import { withStateDb, withStateDbSnapshot } from './storage/sqlite.js';
 
 const PATTERN_CONFIDENCE_THRESHOLD = 0.6;
@@ -55,6 +56,7 @@ const computeTaskSimilarity = (task1, task2) => {
 
 export const recordContextAccess = async ({ task, intent, files }) => {
   if (!task || !Array.isArray(files) || files.length === 0) return;
+  if (getRepoMutationSafety().shouldBlock) return null;
 
   const signature = normalizeTaskSignature(task);
   if (!signature) return;
@@ -174,6 +176,15 @@ export const predictContextFiles = async ({ task, intent, maxFiles = MAX_PREDICT
 };
 
 export const cleanupStalePatterns = async ({ retentionDays = PATTERN_DECAY_DAYS } = {}) => {
+  if (getRepoMutationSafety().shouldBlock) {
+    return {
+      action: 'cleanup_patterns',
+      deletedPatterns: 0,
+      retentionDays,
+      blocked: true,
+    };
+  }
+
   return withStateDb((db) => {
     initPatternTables(db);