@kaddo/mcp 3.23.2 → 3.25.0

package/dist/index.js

@@ -2086,6 +2086,129 @@ function renderExplanationAgent(exp) {
   return JSON.stringify({ ...rest, mapped_modules: mappedModules }, null, 2) + "\n";
 }
 
+// ../cli/src/core/guard-history.ts
+var HISTORY_DIR = ".kaddo/history";
+var RUNS_PATH = `${HISTORY_DIR}/guard-runs.jsonl`;
+var SUMMARY_PATH = `${HISTORY_DIR}/guard-summary.json`;
+function toPosix5(p) {
+  return p.replace(/\\/g, "/");
+}
+function loadGuardRuns(dir) {
+  const p = join(dir, RUNS_PATH);
+  if (!exists(p)) return [];
+  const out = [];
+  for (const line of readFile(p).split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      out.push(JSON.parse(t));
+    } catch {
+    }
+  }
+  return out;
+}
+function resolveDriftThreads(runs) {
+  const sorted = [...runs].sort((a, b) => a.generated_at.localeCompare(b.generated_at));
+  const paths = /* @__PURE__ */ new Set();
+  for (const r of sorted) for (const w of r.warnings) paths.add(w.code_path);
+  const threads = [];
+  for (const codePath of paths) {
+    const related = /* @__PURE__ */ new Set();
+    let firstDetected = "";
+    let lastWarn = "";
+    for (const r of sorted) {
+      const w = r.warnings.find((x) => x.code_path === codePath);
+      if (w) {
+        if (!firstDetected) firstDetected = r.generated_at;
+        lastWarn = r.generated_at;
+        for (const a of w.related_artifacts) related.add(a);
+      }
+    }
+    let resolvedAt;
+    for (const r of sorted) {
+      if (r.generated_at <= lastWarn) continue;
+      const touched = r.touched_files.some((f) => toPosix5(f) === codePath);
+      const warnedHere = r.warnings.some((x) => x.code_path === codePath);
+      const updatedRelated = r.updated_artifacts.some((a) => related.has(a));
+      if (touched && updatedRelated && !warnedHere) {
+        resolvedAt = r.generated_at;
+        break;
+      }
+    }
+    threads.push({
+      code_path: codePath,
+      related_artifacts: [...related],
+      first_detected: firstDetected,
+      last_seen: lastWarn,
+      status: resolvedAt ? "resolved" : "open",
+      ...resolvedAt ? { resolved_at: resolvedAt } : {}
+    });
+  }
+  return threads;
+}
+function hotspotDir(codePath) {
+  const i = codePath.lastIndexOf("/");
+  return i >= 0 ? codePath.slice(0, i + 1) : codePath;
+}
+function computeTrend(runs) {
+  if (runs.length < 2) return { direction: "unknown", reason: "Not enough recorded runs to detect a trend." };
+  const sorted = [...runs].sort((a, b) => a.generated_at.localeCompare(b.generated_at));
+  const mid = Math.floor(sorted.length / 2);
+  const avg = (arr) => arr.length ? arr.reduce((s, r) => s + r.warnings.length, 0) / arr.length : 0;
+  const earlier = avg(sorted.slice(0, mid));
+  const recent = avg(sorted.slice(mid));
+  if (recent < earlier) return { direction: "improving", reason: "Fewer warnings in the last recorded runs." };
+  if (recent > earlier) return { direction: "worsening", reason: "More warnings in the last recorded runs." };
+  return { direction: "stable", reason: "Warning volume is roughly stable across recorded runs." };
+}
+function buildGuardHistory(dir) {
+  const runs = loadGuardRuns(dir);
+  if (runs.length === 0) {
+    return {
+      available: false,
+      total_runs: 0,
+      first_run: null,
+      last_run: null,
+      runs_with_warnings: 0,
+      runs_clean: 0,
+      detected: 0,
+      open: 0,
+      resolved: 0,
+      resolution_rate: 0,
+      threads: [],
+      hotspots: [],
+      trend: { direction: "unknown", reason: "No guard history recorded yet." }
+    };
+  }
+  const sorted = [...runs].sort((a, b) => a.generated_at.localeCompare(b.generated_at));
+  const threads = resolveDriftThreads(sorted);
+  const open = threads.filter((t) => t.status === "open").length;
+  const resolved = threads.filter((t) => t.status === "resolved").length;
+  const detected = threads.length;
+  const runsWithWarnings = sorted.filter((r) => r.warnings.length > 0).length;
+  const hotspotMap = /* @__PURE__ */ new Map();
+  for (const t of threads) {
+    const d = hotspotDir(t.code_path);
+    hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
+  }
+  const hotspots = [...hotspotMap.entries()].map(([path3, warnings]) => ({ path: path3, warnings })).sort((a, b) => b.warnings - a.warnings);
+  return {
+    available: true,
+    total_runs: sorted.length,
+    first_run: sorted[0].generated_at,
+    last_run: sorted[sorted.length - 1].generated_at,
+    runs_with_warnings: runsWithWarnings,
+    runs_clean: sorted.length - runsWithWarnings,
+    detected,
+    open,
+    resolved,
+    resolution_rate: detected > 0 ? Math.round(resolved / detected * 1e3) / 10 : 0,
+    threads,
+    hotspots,
+    trend: computeTrend(sorted)
+  };
+}
+
 // ../cli/src/core/impact-report.ts
 function isBroadGlob(glob) {
   if (!glob.endsWith("/**")) return false;
@@ -2337,10 +2460,10 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       ready_quality: byState.ready > 0 ? `${byState.ready} ready` : "not applicable"
     },
     graph_quality: g.available ? { available: true, scope: g.scope, quality: g.quality, nodes: g.nodes, edges: g.edges, hints: g.hints, reason: g.scopeReason, last_exported: g.generatedAt } : { available: false, suggestion: "Run `kaddo graph export --scope all`." },
-    guard_activity: {
-      available: false,
-      note: "Guard history is not persisted. Run `kaddo guard` to check drift; future versions may store runs for trend analysis."
-    },
+    guard_activity: (() => {
+      const gh = buildGuardHistory(dir);
+      return gh.available ? { available: true, runs_recorded: gh.total_runs, detected: gh.detected, open: gh.open, resolved: gh.resolved, resolution_rate: gh.resolution_rate } : { available: false, note: "Guard history is not persisted. Run `kaddo guard --record` to record runs for trend analysis." };
+    })(),
     impact_signals,
     actionable_gaps: gaps,
     score,
@@ -2429,8 +2552,18 @@ function renderImpactMarkdown(r) {
   }
   L.push("");
   L.push("## Guard Activity", "");
-  L.push("- Guard history: not available");
-  L.push(`- Note: ${r.guard_activity.note}`);
+  if (r.guard_activity.available) {
+    const ga = r.guard_activity;
+    L.push("- Guard history: available");
+    L.push(`- Guard runs recorded: ${ga.runs_recorded}`);
+    L.push(`- Drift warnings detected: ${ga.detected}`);
+    L.push(`- Open warnings: ${ga.open}`);
+    L.push(`- Resolved warnings: ${ga.resolved}`);
+    L.push(`- Resolution rate: ${ga.resolution_rate}%`);
+  } else {
+    L.push("- Guard history: not available");
+    L.push(`- Note: ${r.guard_activity.note}`);
+  }
   L.push("");
   L.push("## Impact Signals", "");
   const s = r.impact_signals;
@@ -2502,6 +2635,327 @@ function serializeImpactJson(r) {
   return JSON.stringify(r, null, 2) + "\n";
 }
 
+// ../cli/src/core/savings.ts
+import { parse as parseYaml6 } from "yaml";
+var DEFAULT_ASSUMPTIONS = {
+  currency: "USD",
+  hourly_cost: 40,
+  context_preparation_minutes_saved_per_work_item: 30,
+  rework_hours_avoided_per_resolved_drift: 2,
+  onboarding_hours_saved_per_new_contributor: 4,
+  review_minutes_saved_per_work_item_with_ownership: 20,
+  clarification_minutes_saved_per_ready_work_item: 25,
+  architecture_discovery_hours_saved_when_graph_good: 3,
+  expected_new_contributors_per_month: 1,
+  expected_work_items_per_month: 8
+};
+var SAVINGS_PATH = ".kaddo/savings.yml";
+function loadAssumptions(dir) {
+  const p = join(dir, SAVINGS_PATH);
+  if (!exists(p)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
+  try {
+    const raw = parseYaml6(readFile(p));
+    const a = raw?.assumptions ?? {};
+    const t = raw?.team ?? {};
+    const num = (v, d) => typeof v === "number" && Number.isFinite(v) ? v : d;
+    return {
+      source: "file",
+      assumptions: {
+        currency: raw?.currency ?? DEFAULT_ASSUMPTIONS.currency,
+        hourly_cost: num(raw?.hourly_cost, DEFAULT_ASSUMPTIONS.hourly_cost),
+        context_preparation_minutes_saved_per_work_item: num(a.context_preparation_minutes_saved_per_work_item, DEFAULT_ASSUMPTIONS.context_preparation_minutes_saved_per_work_item),
+        rework_hours_avoided_per_resolved_drift: num(a.rework_hours_avoided_per_resolved_drift, DEFAULT_ASSUMPTIONS.rework_hours_avoided_per_resolved_drift),
+        onboarding_hours_saved_per_new_contributor: num(a.onboarding_hours_saved_per_new_contributor, DEFAULT_ASSUMPTIONS.onboarding_hours_saved_per_new_contributor),
+        review_minutes_saved_per_work_item_with_ownership: num(a.review_minutes_saved_per_work_item_with_ownership, DEFAULT_ASSUMPTIONS.review_minutes_saved_per_work_item_with_ownership),
+        clarification_minutes_saved_per_ready_work_item: num(a.clarification_minutes_saved_per_ready_work_item, DEFAULT_ASSUMPTIONS.clarification_minutes_saved_per_ready_work_item),
+        architecture_discovery_hours_saved_when_graph_good: num(a.architecture_discovery_hours_saved_when_graph_good, DEFAULT_ASSUMPTIONS.architecture_discovery_hours_saved_when_graph_good),
+        expected_new_contributors_per_month: num(t.expected_new_contributors_per_month, DEFAULT_ASSUMPTIONS.expected_new_contributors_per_month),
+        expected_work_items_per_month: num(t.expected_work_items_per_month, DEFAULT_ASSUMPTIONS.expected_work_items_per_month)
+      }
+    };
+  } catch {
+    return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
+  }
+}
+var READINESS_MULT = { Low: 0.25, Medium: 0.5, High: 0.75, "Very High": 1 };
+var GRAPH_MULT = { empty: 0, sparse: 0.25, partial: 0.6, good: 1, unknown: 0 };
+var round2 = (n) => Math.round(n * 100) / 100;
+function parseRatioNumerator(s) {
+  const m = s.match(/^(\d+)/);
+  return m ? Number(m[1]) : 0;
+}
+var SAVINGS_DISCLAIMER = "These are evidence-based estimates, not exact ROI. Adjust assumptions with real team data.";
+function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
+  const { assumptions: a, source } = loadAssumptions(dir);
+  const impact = buildImpactReport(dir, { scope: opts.scope, scopeSource: opts.scopeSource }, now);
+  const completed = impact.traceability.completed_work_items;
+  const wiWithOwnership = parseRatioNumerator(impact.traceability.work_items_connected_to_code);
+  const acceptanceCov = impact.knowledge_coverage.find((c) => c.label.toLowerCase().includes("acceptance"));
+  const wiWithAcceptance = acceptanceCov?.have ?? 0;
+  const graphQuality = impact.graph_quality.available ? impact.graph_quality.quality : "unknown";
+  const readiness = impact.context_readiness.level;
+  const ctxPrepH = round2(completed * a.context_preparation_minutes_saved_per_work_item / 60);
+  const reviewH = round2(wiWithOwnership * a.review_minutes_saved_per_work_item_with_ownership / 60);
+  const clarH = round2(wiWithAcceptance * a.clarification_minutes_saved_per_ready_work_item / 60);
+  const readinessMult = READINESS_MULT[readiness] ?? 0.5;
+  const onboardH = round2(a.expected_new_contributors_per_month * a.onboarding_hours_saved_per_new_contributor * readinessMult);
+  const graphMult = GRAPH_MULT[graphQuality] ?? 0;
+  const archH = round2(a.architecture_discovery_hours_saved_when_graph_good * graphMult);
+  const guard = buildGuardHistory(dir);
+  const driftSavings = guard.available && guard.resolved > 0 ? {
+    available: true,
+    hours: round2(guard.resolved * a.rework_hours_avoided_per_resolved_drift),
+    formula: `${guard.resolved} resolved drift warnings \xD7 ${a.rework_hours_avoided_per_resolved_drift} h`
+  } : { available: false, hours: 0, reason: "Guard history is not persisted yet." };
+  const totalHours = round2(ctxPrepH + reviewH + clarH + onboardH + archH + driftSavings.hours);
+  const totalValue = Math.round(totalHours * a.hourly_cost);
+  const reasons = [];
+  let level;
+  if (impact.score === null || impact.score < 60 || graphQuality === "empty") {
+    level = "Low";
+    reasons.push("Impact score is low or the knowledge graph is empty.");
+  } else if (impact.score >= 85 && graphQuality === "good" && source === "file" && guard.available && guard.resolved > 0) {
+    level = "High";
+    reasons.push("Strong evidence, custom assumptions and recorded drift resolution.");
+  } else {
+    level = "Medium";
+    reasons.push("Strong knowledge and graph evidence.");
+  }
+  if (!guard.available) reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
+  else reasons.push(`Guard history available (${guard.resolved} resolved drift warning(s)).`);
+  reasons.push(source === "file" ? "Assumptions come from `.kaddo/savings.yml`." : "Savings assumptions are defaults and should be calibrated.");
+  const actions = [];
+  if (source === "default") actions.push("Run `kaddo savings init` to customize assumptions.");
+  actions.push("Calibrate hourly cost and team assumptions with real team data.");
+  actions.push("Run `kaddo impact` to verify the underlying evidence quality.");
+  actions.push("Use this report as directional evidence, not accounting data.");
+  actions.push("Future: persist Guard history to estimate avoided rework.");
+  return {
+    generated_at: now.toISOString(),
+    project: impact.project,
+    scope: impact.scope,
+    currency: a.currency,
+    disclaimer: SAVINGS_DISCLAIMER,
+    assumptions_source: source,
+    assumptions: {
+      hourly_cost: a.hourly_cost,
+      context_preparation_minutes_saved_per_work_item: a.context_preparation_minutes_saved_per_work_item,
+      review_minutes_saved_per_work_item_with_ownership: a.review_minutes_saved_per_work_item_with_ownership,
+      clarification_minutes_saved_per_ready_work_item: a.clarification_minutes_saved_per_ready_work_item,
+      onboarding_hours_saved_per_new_contributor: a.onboarding_hours_saved_per_new_contributor,
+      expected_new_contributors_per_month: a.expected_new_contributors_per_month,
+      architecture_discovery_hours_saved_when_graph_good: a.architecture_discovery_hours_saved_when_graph_good
+    },
+    evidence: {
+      knowledge_impact_score: impact.score,
+      completed_work_items: completed,
+      ownership_coverage_percent: impact.ownership_coverage.coverage_percent,
+      work_items_with_acceptance_criteria: acceptanceCov ? `${acceptanceCov.have}/${acceptanceCov.total}` : "0/0",
+      graph_quality: graphQuality,
+      graph_nodes: impact.graph_quality.available ? impact.graph_quality.nodes : null,
+      graph_edges: impact.graph_quality.available ? impact.graph_quality.edges : null,
+      context_readiness: readiness,
+      guard_history_available: guard.available
+    },
+    estimated_savings: {
+      context_preparation: { hours: ctxPrepH, formula: `${completed} Work Items \xD7 ${a.context_preparation_minutes_saved_per_work_item} min` },
+      review_effort: { hours: reviewH, formula: `${wiWithOwnership} Work Items with ownership \xD7 ${a.review_minutes_saved_per_work_item_with_ownership} min` },
+      clarification_reduction: { hours: clarH, formula: `${wiWithAcceptance} Work Items with Acceptance Criteria \xD7 ${a.clarification_minutes_saved_per_ready_work_item} min` },
+      onboarding: { hours: onboardH, formula: `${a.expected_new_contributors_per_month} contributor \xD7 ${a.onboarding_hours_saved_per_new_contributor} h \xD7 ${readinessMult.toFixed(2)} readiness multiplier` },
+      architecture_discovery: { hours: archH, formula: `${a.architecture_discovery_hours_saved_when_graph_good} h \xD7 ${graphMult.toFixed(2)} graph multiplier` },
+      drift_prevention: driftSavings
+    },
+    total: { estimated_hours_saved: totalHours, estimated_value: totalValue, currency: a.currency },
+    confidence: { level, reasons },
+    suggested_actions: actions
+  };
+}
+function renderSavingsMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Estimated Savings Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push(`Scope: ${r.scope}`);
+  L.push(`Currency: ${r.currency}`);
+  L.push("");
+  L.push("## Disclaimer", "");
+  L.push(r.disclaimer, "");
+  L.push("## Executive Summary", "");
+  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} hours`);
+  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
+  L.push(`- Confidence: ${r.confidence.level}`);
+  if (r.assumptions_source === "default") L.push("- Using default assumptions. Run `kaddo savings init` to customize them.");
+  L.push("");
+  L.push("## Assumptions", "");
+  L.push(`- Hourly cost: ${r.assumptions.hourly_cost} ${r.currency}`);
+  L.push(`- Context preparation saved per Work Item: ${r.assumptions.context_preparation_minutes_saved_per_work_item} min`);
+  L.push(`- Review saved per Work Item with ownership: ${r.assumptions.review_minutes_saved_per_work_item_with_ownership} min`);
+  L.push(`- Clarification saved per Work Item with acceptance criteria: ${r.assumptions.clarification_minutes_saved_per_ready_work_item} min`);
+  L.push(`- Onboarding saved per new contributor: ${r.assumptions.onboarding_hours_saved_per_new_contributor} h`);
+  L.push(`- Expected new contributors per month: ${r.assumptions.expected_new_contributors_per_month}`);
+  L.push(`- Architecture discovery saved when graph is good: ${r.assumptions.architecture_discovery_hours_saved_when_graph_good} h`);
+  L.push("");
+  L.push("## Evidence Used", "");
+  const e = r.evidence;
+  L.push(`- Knowledge Impact Score: ${e.knowledge_impact_score ?? "not available"}${e.knowledge_impact_score !== null ? "/100" : ""}`);
+  L.push(`- Completed Work Items: ${e.completed_work_items}`);
+  L.push(`- Ownership coverage: ${e.ownership_coverage_percent}%`);
+  L.push(`- Work Items with Acceptance Criteria: ${e.work_items_with_acceptance_criteria}`);
+  L.push(`- Graph quality: ${e.graph_quality}`);
+  if (e.graph_nodes !== null) L.push(`- Graph nodes: ${e.graph_nodes}`);
+  if (e.graph_edges !== null) L.push(`- Graph edges: ${e.graph_edges}`);
+  L.push(`- Context readiness: ${e.context_readiness}`);
+  L.push("- Guard history: not available");
+  L.push("");
+  L.push("## Estimated Savings", "");
+  const s = r.estimated_savings;
+  const line = (title, l) => {
+    L.push(`### ${title}`, "");
+    L.push(`- Formula: ${l.formula}`);
+    L.push(`- Estimated: ${l.hours} h`, "");
+  };
+  line("Context Preparation", s.context_preparation);
+  line("Review Effort", s.review_effort);
+  line("Clarification Reduction", s.clarification_reduction);
+  line("Onboarding", s.onboarding);
+  line("Architecture Discovery", s.architecture_discovery);
+  L.push("### Drift Prevention", "");
+  if (s.drift_prevention.available) {
+    L.push(`- Formula: ${s.drift_prevention.formula}`);
+    L.push(`- Estimated: ${s.drift_prevention.hours} h`, "");
+  } else {
+    L.push("- Not available yet.");
+    L.push(`- Reason: ${s.drift_prevention.reason}`, "");
+  }
+  L.push("## Total", "");
+  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} h`);
+  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
+  L.push("");
+  L.push("## Confidence", "");
+  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
+  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
+  L.push("");
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
+  L.push("");
+  return L.join("\n");
+}
+function serializeSavingsJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+
+// ../cli/src/core/drift-report.ts
+function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
+  const h = buildGuardHistory(dir);
+  const project = loadConfig(dir)?.project.name ?? "unknown";
+  const actions = [];
+  if (!h.available) {
+    actions.push("Run `kaddo guard --record` to start recording guard history.");
+  } else {
+    if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
+    actions.push("Run `kaddo guard --record` before important commits.");
+    actions.push("Use this report to calibrate estimated drift-prevention savings.");
+  }
+  return {
+    generated_at: now.toISOString(),
+    project,
+    guard_history: {
+      available: h.available,
+      total_runs: h.total_runs,
+      first_run: h.first_run,
+      last_run: h.last_run,
+      runs_with_warnings: h.runs_with_warnings,
+      runs_clean: h.runs_clean
+    },
+    drift_warnings: { detected: h.detected, open: h.open, resolved: h.resolved, resolution_rate: h.resolution_rate },
+    hotspots: h.hotspots,
+    trend: h.trend,
+    threads: h.threads,
+    suggested_actions: actions
+  };
+}
+function renderDriftMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Drift Trend Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push("");
+  if (!r.guard_history.available) {
+    L.push("## Guard History", "");
+    L.push("No guard history recorded yet.");
+    L.push("");
+    L.push("Run `kaddo guard --record` to start recording drift evidence.");
+    L.push("");
+    L.push("## Suggested Actions", "");
+    r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+    L.push("");
+    return L.join("\n");
+  }
+  const w = r.drift_warnings;
+  L.push("## Executive Summary", "");
+  L.push(`- Guard runs recorded: ${r.guard_history.total_runs}`);
+  L.push(`- Drift warnings detected: ${w.detected}`);
+  L.push(`- Open warnings: ${w.open}`);
+  L.push(`- Resolved warnings: ${w.resolved}`);
+  L.push(`- Resolution rate: ${w.resolution_rate}%`);
+  if (r.hotspots.length > 0) L.push(`- Most affected area: ${r.hotspots[0].path}`);
+  L.push("");
+  L.push("## Guard History", "");
+  L.push(`- First run: ${r.guard_history.first_run}`);
+  L.push(`- Last run: ${r.guard_history.last_run}`);
+  L.push(`- Runs with warnings: ${r.guard_history.runs_with_warnings}/${r.guard_history.total_runs}`);
+  L.push(`- Runs clean: ${r.guard_history.runs_clean}/${r.guard_history.total_runs}`);
+  L.push("");
+  L.push("## Drift Warnings", "");
+  const open = r.threads.filter((t) => t.status === "open");
+  const resolved = r.threads.filter((t) => t.status === "resolved");
+  L.push("### Open", "");
+  if (open.length === 0) L.push("_None._", "");
+  for (const t of open) {
+    L.push(`- ${t.code_path}`);
+    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
+    L.push(`  - First detected: ${t.first_detected}`);
+    L.push(`  - Last seen: ${t.last_seen}`);
+    L.push("  - Status: open");
+  }
+  L.push("");
+  L.push("### Resolved", "");
+  if (resolved.length === 0) L.push("_None._", "");
+  for (const t of resolved) {
+    L.push(`- ${t.code_path}`);
+    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
+    L.push(`  - First detected: ${t.first_detected}`);
+    L.push(`  - Resolved at: ${t.resolved_at}`);
+    L.push("  - Status: resolved");
+  }
+  L.push("");
+  L.push("## Hotspots", "");
+  if (r.hotspots.length === 0) L.push("_None._");
+  for (const h of r.hotspots) L.push(`- ${h.path}: ${h.warnings} warning(s)`);
+  L.push("");
+  L.push("## Trend", "");
+  L.push(`- Recent direction: ${r.trend.direction}`);
+  L.push(`- Reason: ${r.trend.reason}`);
+  L.push("");
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+  L.push("");
+  return L.join("\n");
+}
+function serializeDriftJson(r) {
+  const out = {
+    generated_at: r.generated_at,
+    project: r.project,
+    guard_history: r.guard_history,
+    drift_warnings: r.drift_warnings,
+    hotspots: r.hotspots,
+    trend: r.trend,
+    threads: r.threads,
+    suggested_actions: r.suggested_actions
+  };
+  return JSON.stringify(out, null, 2) + "\n";
+}
+
 // src/workitems.ts
 import matter7 from "gray-matter";
 var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
@@ -2714,6 +3168,44 @@ var RESOURCES = [
       }
       return [{ uri: "kaddo://impact-report", text: renderImpactMarkdown(buildImpactReport(root, { scope: "all", scopeSource: "default" })), mimeType: "text/markdown" }];
     }
+  },
+  {
+    uri: "kaddo://savings-report",
+    name: "Kaddo savings report",
+    description: "Estimated Savings Report \u2014 the last written report, or generated in memory (read-only).",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const saved = readText(root, ".kaddo/reports/savings-report.md");
+      if (saved) return [{ uri: "kaddo://savings-report", text: saved, mimeType: "text/markdown" }];
+      if (!hasKnowledge(root)) {
+        return text("kaddo://savings-report", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [{ uri: "kaddo://savings-report", text: renderSavingsMarkdown(buildSavingsReport(root, { scope: "all", scopeSource: "default" })), mimeType: "text/markdown" }];
+    }
+  },
+  {
+    uri: "kaddo://drift-report",
+    name: "Kaddo drift report",
+    description: "Drift Trend Report \u2014 the last written report, or generated in memory (read-only).",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const saved = readText(root, ".kaddo/reports/drift-report.md");
+      if (saved) return [{ uri: "kaddo://drift-report", text: saved, mimeType: "text/markdown" }];
+      return [{ uri: "kaddo://drift-report", text: renderDriftMarkdown(buildDriftReport(root)), mimeType: "text/markdown" }];
+    }
+  },
+  {
+    uri: "kaddo://guard-history",
+    name: "Kaddo guard history",
+    description: "Recorded guard runs (.kaddo/history/guard-runs.jsonl) \u2014 read-only.",
+    mimeType: "application/jsonl",
+    read: (root) => {
+      const runs = readText(root, ".kaddo/history/guard-runs.jsonl");
+      if (runs === null) {
+        return text("kaddo://guard-history", "No guard history recorded yet. Run `kaddo guard --record`.", "text/plain");
+      }
+      return [{ uri: "kaddo://guard-history", text: runs, mimeType: "application/jsonl" }];
+    }
   }
 ];
 
@@ -3492,6 +3984,37 @@ function generateImpactReport(root, opts = {}) {
     next_suggested_resources: ["kaddo://impact-report"]
   };
 }
+function generateSavingsReport(root, opts = {}) {
+  requireConfig(root);
+  requireKnowledge(root);
+  const format = opts.format ?? "markdown";
+  const report = buildSavingsReport(root, { scope: opts.scope ?? "all", scopeSource: opts.scope ? "explicit" : "default" });
+  const content = format === "json" ? serializeSavingsJson(report) : renderSavingsMarkdown(report);
+  const out = opts.output ?? `.kaddo/reports/savings-report.${format === "json" ? "json" : "md"}`;
+  writeDerived(root, out, content);
+  return {
+    status: "ok",
+    files_written: [out.replace(/\\/g, "/")],
+    summary: `Savings report generated (${format}, ${report.scope} scope, ~${report.total.estimated_hours_saved}h).`,
+    warnings: report.assumptions_source === "default" ? ["Using default assumptions \u2014 run `kaddo savings init` to calibrate."] : [],
+    next_suggested_resources: ["kaddo://savings-report"]
+  };
+}
+function generateDriftReport(root, opts = {}) {
+  requireConfig(root);
+  const format = opts.format ?? "markdown";
+  const report = buildDriftReport(root);
+  const content = format === "json" ? serializeDriftJson(report) : renderDriftMarkdown(report);
+  const out = opts.output ?? `.kaddo/reports/drift-report.${format === "json" ? "json" : "md"}`;
+  writeDerived(root, out, content);
+  return {
+    status: "ok",
+    files_written: [out.replace(/\\/g, "/")],
+    summary: report.guard_history.available ? `Drift report generated (${report.drift_warnings.open} open, ${report.drift_warnings.resolved} resolved).` : "Drift report generated (no guard history yet \u2014 run `kaddo guard --record`).",
+    warnings: report.guard_history.available ? [] : ["No guard history recorded yet."],
+    next_suggested_resources: ["kaddo://drift-report"]
+  };
+}
 function generateCapsuleDraft(root) {
   const config = requireConfig(root);
   requireKnowledge(root);
@@ -3692,6 +4215,39 @@ function createServer(root) {
       () => generateImpactReport(root, { format: args.format, scope: args.scope, output: args.output })
     )
   );
+  server.registerTool(
+    "kaddo_generate_savings_report",
+    {
+      title: "Generate savings report",
+      description: `Write the Estimated Savings Report under .kaddo/reports/. format: markdown (default) or json; scope: active or all (default all). Evidence-based estimates, not exact ROI. ${DERIVED_NOTE}`,
+      inputSchema: {
+        format: z2.enum(["markdown", "json"]).optional(),
+        scope: z2.enum(["active", "all"]).optional(),
+        output: z2.string().optional()
+      }
+    },
+    async (args) => generated(
+      root,
+      "generate savings report",
+      () => generateSavingsReport(root, { format: args.format, scope: args.scope, output: args.output })
+    )
+  );
+  server.registerTool(
+    "kaddo_generate_drift_report",
+    {
+      title: "Generate drift report",
+      description: `Write the Drift Trend Report under .kaddo/reports/ from recorded guard history. format: markdown (default) or json. Does NOT record guard runs. ${DERIVED_NOTE}`,
+      inputSchema: {
+        format: z2.enum(["markdown", "json"]).optional(),
+        output: z2.string().optional()
+      }
+    },
+    async (args) => generated(
+      root,
+      "generate drift report",
+      () => generateDriftReport(root, { format: args.format, output: args.output })
+    )
+  );
   server.registerTool(
     "kaddo_generate_capsule_draft",
     { title: "Generate capsule draft", description: `Write a capsule DRAFT under .kaddo/exports/ (never registers it). ${DERIVED_NOTE}`, inputSchema: {} },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.23.2",
+  "version": "3.25.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {