@kaddo/cli 3.22.1 → 3.23.1

package/README.md

@@ -510,6 +510,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.21 | Reusable Skills layer (`kaddo add skills`); skills in context/explain/understand, agent prompts and MCP |
 | v3.22 | Guard & graph scope semantics: graph scope metadata, contextual-empty messaging, Guard ownership scope (active + completed; `--include-archived`) |
 | v3.22.1 | Guard project-root path normalization: matches `code:` globs when the project is a subfolder of the Git root |
+| v3.23 | Knowledge Impact Report: `kaddo report impact` (Markdown/JSON, `--output`); evidence-first health/coverage/traceability/readiness/signals; MCP resource + tool |
+| 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 |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -684,6 +684,10 @@ var COMMAND_HELP = {
   "graph export": {
     question: "How is my project knowledge connected?",
     next: "Open .kaddo/graph.mmd, or run kaddo explain for a summary"
+  },
+  "report impact": {
+    question: "What impact is Kaddo having on this project?",
+    next: "Act on the Suggested Actions section"
   }
 };
 function commandFooterLines(name) {
@@ -10912,6 +10916,435 @@ function runGraphExport(opts = {}) {
   outro2("Knowledge graph ready.");
 }
 
+// src/core/impact-report.ts
+import matter8 from "gray-matter";
+function isBroadGlob(glob) {
+  if (!glob.endsWith("/**")) return false;
+  const prefix = glob.slice(0, -3);
+  return prefix.length > 0 && prefix.split("/").length <= 2;
+}
+function levelFromRatio(r) {
+  if (r >= 0.9) return "Very High";
+  if (r >= 0.7) return "High";
+  if (r >= 0.4) return "Medium";
+  return "Low";
+}
+function hasSection(body, re) {
+  return body.split(/\r?\n/).some((l) => /^#{1,6}\s+/.test(l) && re.test(l));
+}
+function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
+  const exp = buildProjectExplanation(dir);
+  const wis = discoverWorkItems(dir);
+  const total = wis.length;
+  let withOwnership = 0;
+  let withSource = 0;
+  let withInitiative = 0;
+  let withLevel = 0;
+  let withAcceptance = 0;
+  let withDoD = 0;
+  let withValidation = 0;
+  let connectedRoadmap = 0;
+  const globCounts = /* @__PURE__ */ new Map();
+  const globOwners = /* @__PURE__ */ new Map();
+  const gaps = {
+    missing_source: [],
+    missing_initiative: [],
+    missing_code_ownership: [],
+    missing_knowledge_level: [],
+    missing_acceptance_criteria: [],
+    missing_definition_of_done: [],
+    missing_validation: [],
+    broad_ownership_globs: [],
+    ownership_overlaps: []
+  };
+  const gapItem = (wi, action) => ({
+    id: wi.id || wi.title,
+    title: wi.title,
+    status: wi.lifecycle ?? wi.status,
+    path: wi.relPath,
+    suggested_action: action
+  });
+  for (const wi of wis) {
+    const id = wi.id || wi.title;
+    if (wi.codeGlobs.length > 0) withOwnership++;
+    else gaps.missing_code_ownership.push(gapItem(wi, "Add `code:` globs to connect this Work Item to source paths (`kaddo owners suggest`)."));
+    const hasSource = Boolean(wi.sourceId) || wi.source === "roadmap";
+    if (hasSource) withSource++;
+    else gaps.missing_source.push(gapItem(wi, "Add `source` or `source_id` if this Work Item came from the roadmap."));
+    if (hasSource || wi.initiative) connectedRoadmap++;
+    if (wi.initiative) withInitiative++;
+    else gaps.missing_initiative.push(gapItem(wi, "Add `initiative` to connect this Work Item to a delivery initiative."));
+    if (wi.knowledgeLevel) withLevel++;
+    else gaps.missing_knowledge_level.push(gapItem(wi, "Add `knowledge_level` (K0\u2013K4) to the front matter."));
+    for (const g2 of wi.codeGlobs) {
+      globCounts.set(g2, (globCounts.get(g2) ?? 0) + 1);
+      globOwners.set(g2, [...globOwners.get(g2) ?? [], id]);
+      if (isBroadGlob(g2)) {
+        gaps.broad_ownership_globs.push({ id, title: wi.title, glob: g2, suggested_action: "Replace with specific files or narrower module paths." });
+      }
+    }
+    try {
+      const body = matter8(readFile(wi.filePath)).content;
+      if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
+      else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
+      if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
+      else gaps.missing_definition_of_done.push(gapItem(wi, "Add a `## Definition of Done` section."));
+      if (hasSection(body, /how to test|validation|validaci|c[oó]mo probarlo/i)) withValidation++;
+      else gaps.missing_validation.push(gapItem(wi, "Add a `## How to test it` (validation) section."));
+    } catch {
+    }
+  }
+  const ownedCodePaths = [...globCounts.values()].reduce((a, b) => a + b, 0);
+  const broadGlobs = [...globCounts.keys()].filter((g2) => isBroadGlob(g2)).length;
+  for (const [glob, owners] of globOwners) {
+    if (owners.length > 1) {
+      gaps.ownership_overlaps.push({ code_path: glob, work_items: [...new Set(owners)], suggested_action: "Review whether the overlap is expected or should be narrowed." });
+    }
+  }
+  const ownershipOverlaps = gaps.ownership_overlaps.length;
+  let g;
+  if (opts.scope) {
+    const config = loadConfig(dir);
+    if (config) {
+      const graph = buildGraph(dir, config, { scope: opts.scope }, now);
+      const hints = buildGraphHints(dir, graph, now);
+      g = { available: true, scope: graph.scope, scopeReason: graph.scope_reason, nodes: graph.nodes.length, edges: graph.edges.length, quality: hints.quality, hints: hints.summary.hints, generatedAt: graph.generated_at };
+    } else {
+      g = { available: false, scope: opts.scope, scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
+    }
+  } else if (exp.graph) {
+    g = { available: true, scope: exp.graph.scope, scopeReason: exp.graph.scopeReason, nodes: exp.graph.nodes, edges: exp.graph.edges, quality: exp.graphHints?.quality ?? "unknown", hints: exp.graphHints?.totalHints ?? 0, generatedAt: exp.graph.generatedAt };
+  } else {
+    g = { available: false, scope: "n/a", scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
+  }
+  const layerStatus = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
+  const byState = exp.workItems.byState;
+  const skills = discoverInstalledSkills(dir);
+  const knowledge_health = {
+    Business: layerStatus("Business"),
+    Product: layerStatus("Product"),
+    Tech: layerStatus("Tech"),
+    Delivery: layerStatus("Delivery"),
+    Inventory: exp.knowledge.hasInventory ? "available" : "missing",
+    "Context pack": exp.knowledge.hasContextPack ? "available" : "missing",
+    Agents: exp.knowledge.hasAgents ? "available" : "missing",
+    Skills: skills.length > 0 ? "available" : "missing"
+  };
+  const knowledge_coverage = [
+    { label: "Work Items with ownership", have: withOwnership, total },
+    { label: "Work Items with source", have: withSource, total },
+    { label: "Work Items with initiative", have: withInitiative, total },
+    { label: "Work Items with acceptance criteria", have: withAcceptance, total },
+    { label: "Work Items with Definition of Done", have: withDoD, total },
+    { label: "Work Items with knowledge level", have: withLevel, total }
+  ];
+  const coverageRatio = (have) => total > 0 ? have / total : 0;
+  const deliveryTraceable = ["Traceable", "Structured", "Consolidated"].includes(layerStatus("Delivery"));
+  const ctxReasons = [];
+  let ctxScore = 0;
+  if (["Consolidated", "Structured"].includes(layerStatus("Business"))) {
+    ctxScore++;
+    ctxReasons.push("Business knowledge is present.");
+  }
+  if (["Consolidated", "Structured"].includes(layerStatus("Product"))) {
+    ctxScore++;
+    ctxReasons.push("Product knowledge is present.");
+  }
+  if (layerStatus("Tech") !== "Missing") {
+    ctxScore++;
+    ctxReasons.push("Tech knowledge is structured.");
+  }
+  if (deliveryTraceable) {
+    ctxScore++;
+    ctxReasons.push("Delivery is traceable.");
+  }
+  if (exp.knowledge.hasContextPack) {
+    ctxScore++;
+    ctxReasons.push("Context pack is available.");
+  }
+  if (g.available && g.quality !== "empty") {
+    ctxScore++;
+    ctxReasons.push(`Graph quality is ${g.quality}.`);
+  }
+  const ctxLevel = ctxScore >= 6 ? "Very High" : ctxScore >= 4 ? "High" : ctxScore >= 2 ? "Medium" : "Low";
+  const ambiguityRatio = total > 0 ? (withAcceptance + withDoD + withSource) / (3 * total) : 0;
+  const aiReady = exp.knowledge.hasContextPack && g.available && g.quality !== "empty" && skills.length > 0 && deliveryTraceable ? "High" : exp.knowledge.hasContextPack && g.available && g.quality !== "empty" ? "Medium" : "Low";
+  const onboarding = levelFromRatio(
+    [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * (exp.knowledge.hasContextPack ? 1 : 0.6)
+  );
+  const deliveryTrace = levelFromRatio(
+    coverageRatio(withOwnership) * 0.5 + (g.available && g.edges > 0 ? 1 : 0) * 0.25 + (exp.roadmap.present ? 1 : 0) * 0.25
+  );
+  const impact_signals = {
+    ambiguity_reduction: levelFromRatio(ambiguityRatio),
+    drift_prevention: withOwnership > 0 ? "Active" : "Limited",
+    onboarding_support: onboarding,
+    delivery_traceability: deliveryTrace,
+    ai_context_readiness: aiReady,
+    maintenance_readiness: levelFromRatio((coverageRatio(withOwnership) + (deliveryTraceable ? 1 : 0)) / 2)
+  };
+  let score = null;
+  let score_breakdown = null;
+  if (total > 0) {
+    const healthPts = [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * 20;
+    const covAvg = knowledge_coverage.reduce((a, c) => a + coverageRatio(c.have), 0) / knowledge_coverage.length;
+    const coveragePts = covAvg * 20;
+    const ownPts = coverageRatio(withOwnership) * 15;
+    const traceBlend = (exp.roadmap.candidates > 0 ? exp.roadmap.materialized / exp.roadmap.candidates : 1) * 0.5 + coverageRatio(withOwnership) * 0.5;
+    const tracePts = traceBlend * 20;
+    const qualityMap = { good: 1, partial: 0.6, sparse: 0.3, empty: 0, unknown: 0 };
+    const graphPts = (g.available ? qualityMap[g.quality] ?? 0 : 0) * 15;
+    const ctxPts = { Low: 0.25, Medium: 0.5, High: 0.8, "Very High": 1 }[ctxLevel] * 10;
+    score = Math.round(healthPts + coveragePts + ownPts + tracePts + graphPts + ctxPts);
+    score_breakdown = {
+      knowledge_health: { points: Math.round(healthPts), max: 20 },
+      knowledge_coverage: { points: Math.round(coveragePts), max: 20 },
+      ownership_coverage: { points: Math.round(ownPts), max: 15 },
+      traceability: { points: Math.round(tracePts), max: 20 },
+      graph_quality: { points: Math.round(graphPts), max: 15 },
+      context_readiness: { points: Math.round(ctxPts), max: 10 }
+    };
+  }
+  const idsOf = (items) => items.map((i) => i.id);
+  const groupedAction = (items, verb) => {
+    if (items.length === 0) return null;
+    const ids = idsOf(items);
+    return ids.length <= 3 ? `${verb} ${ids.join(", ")}.` : `${verb} ${ids.length} Work Items: ${ids.slice(0, 3).join(", ")}, \u2026`;
+  };
+  const actions = [];
+  if (!g.available) actions.push("Run `kaddo graph export --scope all` to inspect full traceability.");
+  else if (g.scope === "active" && g.quality === "empty") actions.push("Run `kaddo graph export --scope all` to include completed Work Items.");
+  if (exp.roadmap.remaining > 0) actions.push(`Materialize the ${exp.roadmap.remaining} remaining roadmap candidate(s) with \`kaddo create --from roadmap\`.`);
+  for (const a of [
+    groupedAction(gaps.missing_code_ownership, "Add `code:` ownership to"),
+    groupedAction(gaps.missing_source, "Add `source`/`source_id` to"),
+    groupedAction(gaps.missing_initiative, "Add an `initiative` to"),
+    groupedAction(gaps.missing_acceptance_criteria, "Add Acceptance Criteria to"),
+    groupedAction(gaps.missing_definition_of_done, "Add a Definition of Done to"),
+    groupedAction(gaps.missing_validation, "Add a validation (How to test it) section to")
+  ]) if (a) actions.push(a);
+  if (gaps.broad_ownership_globs.length > 0) actions.push(`Narrow ${gaps.broad_ownership_globs.length} broad ownership glob(s) into specific paths.`);
+  if (g.available && g.hints > 0) actions.push("Review graph hints (`kaddo://graph-hints` or `.kaddo/graph-hints.md`).");
+  if (skills.length === 0) actions.push("Install reusable skills with `kaddo add skills`.");
+  actions.push("Run `kaddo guard` before committing to catch knowledge drift.");
+  const summary = [];
+  if (total > 0) summary.push(`${withOwnership}/${total} Work Items include code ownership.`);
+  if (g.available) summary.push(`The knowledge graph is ${g.quality} with ${g.nodes} nodes and ${g.edges} edges (${g.scope} scope).`);
+  else summary.push("The knowledge graph has not been exported yet.");
+  if (g.available) summary.push(g.hints === 0 ? "No graph hints are currently open." : `${g.hints} graph hint(s) are open.`);
+  if (exp.roadmap.present) summary.push(`Delivery: ${exp.roadmap.materialized} materialized, ${exp.roadmap.remaining} roadmap candidate(s) remaining.`);
+  summary.push(`Context readiness: ${ctxLevel}.`);
+  return {
+    generated_at: now.toISOString(),
+    project: exp.project.name,
+    scope: g.scope,
+    executive_summary: summary,
+    knowledge_health,
+    knowledge_coverage,
+    ownership_coverage: {
+      coverage_percent: total > 0 ? Math.round(withOwnership / total * 100) : 0,
+      work_items_with_ownership: `${withOwnership}/${total}`,
+      owned_code_paths: ownedCodePaths,
+      broad_globs: broadGlobs,
+      ownership_overlaps: ownershipOverlaps
+    },
+    traceability: {
+      roadmap_candidates: exp.roadmap.candidates,
+      materialized_work_items: exp.roadmap.materialized,
+      remaining_candidates: exp.roadmap.remaining,
+      completed_work_items: byState.completed,
+      work_items_connected_to_roadmap: `${connectedRoadmap}/${total}`,
+      work_items_connected_to_code: `${withOwnership}/${total}`,
+      graph_quality: g.available ? g.quality : "not available",
+      graph_nodes: g.available ? g.nodes : null,
+      graph_edges: g.available ? g.edges : null,
+      graph_hints: g.available ? g.hints : null
+    },
+    context_readiness: { level: ctxLevel, reasons: ctxReasons },
+    work_item_readiness: {
+      draft: byState.draft,
+      ready: byState.ready,
+      in_progress: byState["in-progress"],
+      blocked: byState.blocked,
+      completed: byState.completed,
+      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."
+    },
+    impact_signals,
+    actionable_gaps: gaps,
+    score,
+    score_breakdown,
+    suggested_actions: actions
+  };
+}
+function ratio(have, total) {
+  return `${have}/${total}`;
+}
+function renderImpactMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Knowledge Impact Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push(`Scope: ${r.scope}`);
+  if (r.score !== null) L.push(`Knowledge Impact Score: ${r.score}/100`);
+  else L.push("Knowledge Impact Score: not available");
+  L.push("");
+  L.push("## Executive Summary", "");
+  for (const s2 of r.executive_summary) L.push(`- ${s2}`);
+  L.push("");
+  L.push("## Knowledge Health", "");
+  for (const [k, v] of Object.entries(r.knowledge_health)) L.push(`- ${k}: ${v}`);
+  L.push("");
+  L.push("## Knowledge Coverage", "");
+  for (const c of r.knowledge_coverage) L.push(`- ${c.label}: ${ratio(c.have, c.total)}`);
+  L.push("");
+  L.push("## Ownership Coverage", "");
+  L.push(`- Coverage: ${r.ownership_coverage.coverage_percent}%`);
+  L.push(`- Work Items with code ownership: ${r.ownership_coverage.work_items_with_ownership}`);
+  L.push(`- Owned code paths: ${r.ownership_coverage.owned_code_paths}`);
+  L.push(`- Broad globs detected: ${r.ownership_coverage.broad_globs}`);
+  L.push(`- Ownership overlaps: ${r.ownership_coverage.ownership_overlaps}`);
+  L.push("");
+  L.push("## Traceability", "");
+  const t = r.traceability;
+  L.push(`- Roadmap candidates: ${t.roadmap_candidates}`);
+  L.push(`- Materialized Work Items: ${t.materialized_work_items}`);
+  L.push(`- Remaining candidates: ${t.remaining_candidates}`);
+  L.push(`- Completed Work Items: ${t.completed_work_items}`);
+  L.push(`- Work Items connected to roadmap: ${t.work_items_connected_to_roadmap}`);
+  L.push(`- Work Items connected to code: ${t.work_items_connected_to_code}`);
+  L.push(`- Graph quality: ${t.graph_quality}`);
+  if (t.graph_nodes !== null) L.push(`- Graph nodes: ${t.graph_nodes}`);
+  if (t.graph_edges !== null) L.push(`- Graph edges: ${t.graph_edges}`);
+  if (t.graph_hints !== null) L.push(`- Graph hints: ${t.graph_hints}`);
+  L.push("");
+  L.push("## Context Readiness", "");
+  L.push(`Context Readiness: ${r.context_readiness.level}`);
+  if (r.context_readiness.reasons.length > 0) {
+    L.push("", "Reason:");
+    for (const reason of r.context_readiness.reasons) L.push(`- ${reason}`);
+  }
+  L.push("");
+  L.push("## Work Item Readiness", "");
+  const w = r.work_item_readiness;
+  L.push(`- Draft: ${w.draft}`);
+  L.push(`- Ready: ${w.ready}`);
+  L.push(`- In Progress: ${w.in_progress}`);
+  L.push(`- Blocked: ${w.blocked}`);
+  L.push(`- Completed: ${w.completed}`);
+  L.push(`- Ready quality: ${w.ready_quality}`);
+  L.push("");
+  L.push("## Graph Quality", "");
+  if (r.graph_quality.available) {
+    const gq = r.graph_quality;
+    L.push(`- Scope: ${gq.scope}`);
+    L.push(`- Quality: ${gq.quality}`);
+    L.push(`- Nodes: ${gq.nodes}`);
+    L.push(`- Edges: ${gq.edges}`);
+    L.push(`- Hints: ${gq.hints}`);
+    if (gq.reason) L.push(`- Reason: ${gq.reason}`);
+    if (gq.last_exported) L.push(`- Last exported: ${gq.last_exported}`);
+  } else {
+    L.push("- Graph data not available.");
+    L.push(`- Tip: ${r.graph_quality.suggestion}`);
+  }
+  L.push("");
+  L.push("## Guard Activity", "");
+  L.push("- Guard history: not available");
+  L.push(`- Note: ${r.guard_activity.note}`);
+  L.push("");
+  L.push("## Impact Signals", "");
+  const s = r.impact_signals;
+  L.push(`- Ambiguity reduction: ${s.ambiguity_reduction}`);
+  L.push(`- Drift prevention: ${s.drift_prevention}`);
+  L.push(`- Onboarding support: ${s.onboarding_support}`);
+  L.push(`- Delivery traceability: ${s.delivery_traceability}`);
+  L.push(`- AI context readiness: ${s.ai_context_readiness}`);
+  L.push(`- Maintenance readiness: ${s.maintenance_readiness}`);
+  L.push("");
+  L.push("## Actionable Gaps", "");
+  const gp = r.actionable_gaps;
+  const gapSection = (title, items) => {
+    if (items.length === 0) return;
+    L.push(`### ${title}`, "");
+    for (const it of items) {
+      L.push(`- ${it.id} \u2014 ${it.title}`);
+      L.push(`  - Path: ${it.path}`);
+      L.push(`  - Suggested action: ${it.suggested_action}`);
+    }
+    L.push("");
+  };
+  gapSection("Work Items missing source", gp.missing_source);
+  gapSection("Work Items missing initiative", gp.missing_initiative);
+  gapSection("Work Items missing code ownership", gp.missing_code_ownership);
+  gapSection("Work Items missing knowledge level", gp.missing_knowledge_level);
+  gapSection("Work Items missing acceptance criteria", gp.missing_acceptance_criteria);
+  gapSection("Work Items missing Definition of Done", gp.missing_definition_of_done);
+  gapSection("Work Items missing validation", gp.missing_validation);
+  if (gp.broad_ownership_globs.length > 0) {
+    L.push("### Broad ownership globs", "");
+    for (const b of gp.broad_ownership_globs) {
+      L.push(`- ${b.id} \u2014 ${b.title}`);
+      L.push(`  - Glob: \`${b.glob}\``);
+      L.push(`  - Suggested action: ${b.suggested_action}`);
+    }
+    L.push("");
+  }
+  if (gp.ownership_overlaps.length > 0) {
+    L.push("### Ownership overlaps", "");
+    for (const o of gp.ownership_overlaps) {
+      L.push(`- \`${o.code_path}\``);
+      L.push(`  - Owned by: ${o.work_items.join(", ")}`);
+      L.push(`  - Suggested action: ${o.suggested_action}`);
+    }
+    L.push("");
+  }
+  const anyGaps = gp.missing_source.length + gp.missing_initiative.length + gp.missing_code_ownership.length + gp.missing_knowledge_level.length + gp.missing_acceptance_criteria.length + gp.missing_definition_of_done.length + gp.missing_validation.length + gp.broad_ownership_globs.length + gp.ownership_overlaps.length;
+  if (anyGaps === 0) {
+    L.push("No actionable knowledge gaps detected. \u{1F389}", "");
+  }
+  if (r.score_breakdown) {
+    L.push("## Score Breakdown", "");
+    const b = r.score_breakdown;
+    L.push(`- Knowledge Health: ${b.knowledge_health.points}/${b.knowledge_health.max}`);
+    L.push(`- Knowledge Coverage: ${b.knowledge_coverage.points}/${b.knowledge_coverage.max}`);
+    L.push(`- Ownership Coverage: ${b.ownership_coverage.points}/${b.ownership_coverage.max}`);
+    L.push(`- Traceability: ${b.traceability.points}/${b.traceability.max}`);
+    L.push(`- Graph Quality: ${b.graph_quality.points}/${b.graph_quality.max}`);
+    L.push(`- Context Readiness: ${b.context_readiness.points}/${b.context_readiness.max}`);
+    L.push("");
+  }
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+  L.push("");
+  return L.join("\n");
+}
+function serializeImpactJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+
+// src/commands/report.ts
+function runReportImpact(opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  const report = buildImpactReport(dir);
+  const content = opts.json ? serializeImpactJson(report) : renderImpactMarkdown(report);
+  if (opts.output) {
+    intro2("kaddo report impact");
+    const rel = opts.output;
+    writeFile(join(dir, rel), content);
+    log2.success(`Wrote ${rel.replace(/\\/g, "/")}`);
+    printCommandFooter("report impact");
+    outro2("Impact report written.");
+    return;
+  }
+  console.log(content);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -10940,6 +11373,13 @@ var graphCmd = program.command("graph").description("Export the lightweight, fil
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
   runGraphExport(opts);
 });
+var reportCmd = program.command("report").description("Generate Kaddo reports");
+reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/impact-report.md)").action((opts) => {
+  runReportImpact(opts);
+});
+program.command("impact").description("Alias for `kaddo report impact`").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file").action((opts) => {
+  runReportImpact(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) => {
   await runGuard(opts);
 });

package/package.json

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