@kaddo/cli 3.24.0 → 3.25.1

package/README.md

@@ -514,6 +514,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.23.1 | Impact report Actionable Gaps: per-Work-Item missing source/initiative/ownership/level/acceptance/DoD/validation, broad globs, overlaps; Work-Item-specific Suggested Actions + Score Breakdown |
 | v3.23.2 | Impact report defaults to `all` scope (accumulated impact), graph built in memory; `--scope active`; `scope_source`/`default_scope` in JSON |
 | v3.24 | Estimated Savings Model: `kaddo savings` (+ `savings init`, `.kaddo/savings.yml`); evidence-based time/value estimates, confidence; MCP resource + tool |
+| v3.25 | Guard history & drift trend: `kaddo guard --record`, `kaddo drift`; feeds impact Guard Activity + savings Drift Prevention; MCP drift/guard-history resources + tool |
+| v3.25.1 | Savings guard-history messaging fix: distinguishes "no history" from "history with 0 resolved warnings" (drift prevention available at 0 h) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -692,6 +692,10 @@ var COMMAND_HELP = {
   savings: {
     question: "How much time/value might Kaddo be saving (estimate)?",
     next: "Run `kaddo savings init` to calibrate assumptions"
+  },
+  drift: {
+    question: "Are code and knowledge drifting apart over time?",
+    next: "Review open warnings; `kaddo guard --record` before commits"
   }
 };
 function commandFooterLines(name) {
@@ -5467,6 +5471,162 @@ function collectMatchedDomains(matchedArtifactDomains) {
   return [...seen];
 }
 
+// src/core/guard-history.ts
+import fs2 from "fs";
+var HISTORY_DIR = ".kaddo/history";
+var RUNS_PATH = `${HISTORY_DIR}/guard-runs.jsonl`;
+var SUMMARY_PATH = `${HISTORY_DIR}/guard-summary.json`;
+function toPosix3(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function loadGuardRuns(dir) {
+  const p2 = join(dir, RUNS_PATH);
+  if (!exists(p2)) return [];
+  const out = [];
+  for (const line of readFile(p2).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) => toPosix3(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(([path6, warnings]) => ({ path: path6, 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)
+  };
+}
+function recordGuardRun(dir, input, now = /* @__PURE__ */ new Date()) {
+  const iso = now.toISOString();
+  const run = {
+    run_id: `guard-${iso.replace(/[:.]/g, "-")}`,
+    generated_at: iso,
+    project: input.project,
+    scope: input.scope,
+    touched_files: input.touched_files,
+    matched_artifacts: input.matched_artifacts,
+    updated_artifacts: input.updated_artifacts,
+    warnings: input.warnings,
+    summary: {
+      touched_files: input.touched_files.length,
+      matched_artifacts: input.matched_artifacts.length,
+      warnings: input.warnings.length
+    }
+  };
+  const runsAbs = join(dir, RUNS_PATH);
+  fs2.mkdirSync(join(dir, HISTORY_DIR), { recursive: true });
+  fs2.appendFileSync(runsAbs, JSON.stringify(run) + "\n", "utf-8");
+  const history = buildGuardHistory(dir);
+  const summary = {
+    generated_at: iso,
+    total_runs: history.total_runs,
+    total_warnings: history.detected,
+    open_warnings: history.open,
+    resolved_warnings: history.resolved,
+    last_run_id: run.run_id
+  };
+  writeFile(join(dir, SUMMARY_PATH), JSON.stringify(summary, null, 2) + "\n");
+  return { run, runsPath: RUNS_PATH, summaryPath: SUMMARY_PATH };
+}
+
 // src/commands/guard.ts
 var ARCH_DIR3 = "knowledge";
 var CONFIG_PATH2 = ".kaddo/config.yml";
@@ -5669,6 +5829,47 @@ async function runGuard(opts = {}) {
   const activeMatches = fyiMatches.filter(
     (m) => !isIgnored(ignores, m.artifact.id || m.artifact.title)
   );
+  if (opts.record) {
+    const idOf = (m) => m.artifact.id || m.artifact.title;
+    const matchedArtifacts = [...new Set(result.matches.map(idOf))];
+    const updatedArtifacts = [...new Set(result.matches.filter((m) => m.artifactWasModified).map(idOf))];
+    const byPath = /* @__PURE__ */ new Map();
+    for (const m of result.matches) {
+      for (const f of m.matchedFiles) {
+        const e = byPath.get(f) ?? { related: /* @__PURE__ */ new Set(), updated: /* @__PURE__ */ new Set() };
+        e.related.add(idOf(m));
+        if (m.artifactWasModified) e.updated.add(idOf(m));
+        byPath.set(f, e);
+      }
+    }
+    const warnings = [];
+    for (const [code_path, e] of byPath) {
+      if ([...e.related].some((a) => !e.updated.has(a))) {
+        warnings.push({
+          type: "possible-knowledge-drift",
+          code_path,
+          related_artifacts: [...e.related],
+          updated_artifacts: [...e.updated],
+          status: "open"
+        });
+      }
+    }
+    const project = loadConfig(dir)?.project.name ?? "unknown";
+    const rec = recordGuardRun(dir, {
+      project,
+      scope: includeArchived ? "active-completed-archived" : "active-and-completed",
+      touched_files: touchedFiles,
+      matched_artifacts: matchedArtifacts,
+      updated_artifacts: updatedArtifacts,
+      warnings
+    });
+    if (!jsonMode) {
+      console.log("");
+      console.log("Guard run recorded:");
+      console.log(`- ${rec.runsPath}`);
+      console.log(`- ${rec.summaryPath}`);
+    }
+  }
   if (jsonMode) {
     const ownerMapCI = loadOwners(dir);
     const matchedDomainsCI = collectMatchedDomains(activeMatches.map((m) => m.artifact.domains));
@@ -6106,14 +6307,14 @@ var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
 function scopeStatuses(scope) {
   return scope === "all" ? { included: ALL_STATUSES, excluded: ["archived"] } : { included: ACTIVE_STATUSES, excluded: ["completed", "archived"] };
 }
-function toPosix3(p2) {
+function toPosix4(p2) {
   return p2.replace(/\\/g, "/");
 }
 function slug(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr(a) {
-  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+  return toPosix4(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
 }
 function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   const scope = opts.scope ?? "active";
@@ -6298,14 +6499,14 @@ function loadGraphSummary(dir) {
 
 // src/core/graph-hints.ts
 var KNOWLEDGE3 = "knowledge";
-function toPosix4(p2) {
+function toPosix5(p2) {
   return p2.replace(/\\/g, "/");
 }
 function slug2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr2(a) {
-  return toPosix4(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+  return toPosix5(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
 }
 function capabilityHeadings(dir) {
   const p2 = join(dir, KNOWLEDGE3, "product", "capabilities.md");
@@ -11172,10 +11373,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,
@@ -11264,8 +11465,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;
@@ -11444,25 +11655,59 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   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 totalHours = round2(ctxPrepH + reviewH + clarH + onboardH + archH);
+  const guard = buildGuardHistory(dir);
+  let driftSavings;
+  if (!guard.available) {
+    driftSavings = { available: false, hours: 0, reason: "Guard history is not persisted yet." };
+  } else if (guard.resolved > 0) {
+    driftSavings = {
+      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`
+    };
+  } else {
+    driftSavings = {
+      available: true,
+      hours: 0,
+      formula: `0 resolved drift warnings \xD7 ${a.rework_hours_avoided_per_resolved_drift} h`,
+      reason: "Guard history exists, but no resolved drift warnings have been recorded 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.");
   }
-  reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
+  if (!guard.available) {
+    reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
+  } else if (guard.resolved > 0) {
+    reasons.push(`Guard history available (${guard.resolved} resolved drift warning(s)).`);
+  } else {
+    reasons.push("Guard history available, but no resolved drift warnings have been recorded yet.");
+  }
   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.");
+  if (!guard.available) {
+    actions.push("Future: persist Guard history to estimate avoided rework.");
+  } else if (guard.resolved === 0) {
+    actions.push("Continue running `kaddo guard --record` before important commits to capture resolved drift warnings.");
+    if (guard.open > 0) actions.push("Review open drift warnings with `kaddo drift`.");
+  } else {
+    actions.push("Use drift history to calibrate `rework_hours_avoided_per_resolved_drift`.");
+  }
   return {
     generated_at: now.toISOString(),
     project: impact.project,
@@ -11488,7 +11733,9 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       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: false
+      guard_history_available: guard.available,
+      guard_runs_recorded: guard.total_runs,
+      resolved_drift_warnings: guard.resolved
     },
     estimated_savings: {
       context_preparation: { hours: ctxPrepH, formula: `${completed} Work Items \xD7 ${a.context_preparation_minutes_saved_per_work_item} min` },
@@ -11496,7 +11743,7 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       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: { available: false, hours: 0, reason: "Guard history is not persisted yet." }
+      drift_prevention: driftSavings
     },
     total: { estimated_hours_saved: totalHours, estimated_value: totalValue, currency: a.currency },
     confidence: { level, reasons },
@@ -11538,7 +11785,13 @@ function renderSavingsMarkdown(r) {
   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");
+  if (e.guard_history_available) {
+    L.push("- Guard history: available");
+    L.push(`- Guard runs recorded: ${e.guard_runs_recorded}`);
+    L.push(`- Resolved drift warnings: ${e.resolved_drift_warnings}`);
+  } else {
+    L.push("- Guard history: not available");
+  }
   L.push("");
   L.push("## Estimated Savings", "");
   const s = r.estimated_savings;
@@ -11553,8 +11806,15 @@ function renderSavingsMarkdown(r) {
   line("Onboarding", s.onboarding);
   line("Architecture Discovery", s.architecture_discovery);
   L.push("### Drift Prevention", "");
-  L.push("- Not available yet.");
-  L.push(`- Reason: ${s.drift_prevention.reason}`, "");
+  if (s.drift_prevention.available) {
+    L.push(`- Formula: ${s.drift_prevention.formula}`);
+    L.push(`- Estimated: ${s.drift_prevention.hours} h`);
+    if (s.drift_prevention.reason) L.push(`- Reason: ${s.drift_prevention.reason}`);
+    L.push("");
+  } 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}`);
@@ -11606,6 +11866,135 @@ function runSavingsInit(opts = {}) {
   outro2("Savings assumptions ready.");
 }
 
+// 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/commands/drift.ts
+function runDrift(opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  const report = buildDriftReport(dir);
+  const content = opts.json ? serializeDriftJson(report) : renderDriftMarkdown(report);
+  if (opts.output) {
+    intro2("kaddo drift");
+    writeFile(join(dir, opts.output), content);
+    log2.success(`Wrote ${opts.output.replace(/\\/g, "/")}`);
+    printCommandFooter("drift");
+    outro2("Drift report written.");
+    return;
+  }
+  console.log(content);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -11650,7 +12039,13 @@ var savingsCmd = program.command("savings").description("Estimated Savings Repor
 savingsCmd.command("init").description("Create an editable `.kaddo/savings.yml` with savings assumptions").option("--force", "Overwrite an existing .kaddo/savings.yml").action((opts) => {
   runSavingsInit(opts);
 });
-program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").option("--include-archived", "Include archived Work Items in ownership matching (excluded by default)").action(async (opts) => {
+reportCmd.command("drift").description("Drift Trend Report from recorded guard history (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/drift-report.md)").action((opts) => {
+  runDrift(opts);
+});
+program.command("drift").description("Drift Trend Report from recorded `kaddo guard --record` history").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file").action((opts) => {
+  runDrift(opts);
+});
+program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").option("--include-archived", "Include archived Work Items in ownership matching (excluded by default)").option("--record", "Record this run to .kaddo/history/ for drift trend reporting").action(async (opts) => {
   await runGuard(opts);
 });
 var ignoreCmd = program.command("ignore").description("Manage guard ignore list");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.24.0",
+  "version": "3.25.1",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {