@kaddo/cli 3.22.0 → 3.23.0

package/README.md

@@ -509,6 +509,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.20 | MCP derived tools: safe regeneration of context/explain/understand/graph/capsule-draft under `.kaddo/` |
 | 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 |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -592,8 +592,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path5 = i.path.join(".");
-      return path5 ? `  - ${path5}: ${i.message}` : `  - ${i.message}`;
+      const path6 = i.path.join(".");
+      return path6 ? `  - ${path6}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -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) {
@@ -4902,6 +4906,14 @@ async function isGitRepo(dir) {
     return false;
   }
 }
+async function getGitRoot(dir) {
+  try {
+    const result = await execa("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
+    return result.stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
 async function getUntrackedFiles() {
   try {
     const result = await execa("git", ["ls-files", "--others", "--exclude-standard"]);
@@ -5048,6 +5060,20 @@ function discoverWorkItems(dir) {
 
 // src/core/diff-analysis.ts
 import { minimatch } from "minimatch";
+import path3 from "path";
+function toPosix2(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function normalizeTouchedPathForProject(touchedPath, gitRoot, projectRoot) {
+  const t = toPosix2(touchedPath).replace(/^\.\//, "").replace(/^\/+/, "");
+  if (!gitRoot) return t;
+  const prefix = toPosix2(path3.relative(gitRoot, projectRoot)).replace(/^\.\//, "").replace(/\/+$/, "");
+  if (prefix === "" || prefix === ".") return t;
+  if (prefix.startsWith("..")) return t;
+  if (t === prefix) return null;
+  if (t.startsWith(prefix + "/")) return t.slice(prefix.length + 1);
+  return null;
+}
 function normalizePath(p2) {
   return p2.replace(/\\/g, "/");
 }
@@ -5107,10 +5133,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path5 = join(dir, IGNORE_FILE);
-  if (!exists(path5)) return [];
+  const path6 = join(dir, IGNORE_FILE);
+  if (!exists(path6)) return [];
   try {
-    const raw = readFile(path5);
+    const raw = readFile(path6);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -5118,7 +5144,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path5 = join(dir, IGNORE_FILE);
+  const path6 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -5126,17 +5152,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path5, stringifyYaml2(existing));
+  writeFile(path6, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path5 = join(dir, IGNORE_FILE);
+  const path6 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path5, stringifyYaml2(filtered));
+  writeFile(path6, stringifyYaml2(filtered));
   return true;
 }
 
@@ -5158,11 +5184,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path5 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path5)) return [];
+  const path6 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path6)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path5));
+    parsed = parseYaml5(readFile(path6));
   } catch {
     return [];
   }
@@ -5254,7 +5280,7 @@ async function collectWorkspaceChanges(dir, mode = "head", deps = defaultDeps) {
 }
 
 // src/commands/guard.ts
-import path3 from "path";
+import path4 from "path";
 import { parse as parseYaml7 } from "yaml";
 
 // src/plugins/prisma.ts
@@ -5458,7 +5484,7 @@ function printHeader(touchedFiles) {
 function artifactLabel(artifact, dir) {
   if (artifact.id) return artifact.id;
   if (artifact.title) return artifact.title;
-  const rel = path3.relative(dir, artifact.filePath).split(path3.sep).join("/");
+  const rel = path4.relative(dir, artifact.filePath).split(path4.sep).join("/");
   return rel || artifact.filePath;
 }
 function printWorkspaceHeader(scan2) {
@@ -5524,7 +5550,7 @@ async function offerIgnore(dir, match) {
   log2.success(`${id} added to .kaddo/ignores.yml`);
   return true;
 }
-function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace, includeArchived) {
+function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace, includeArchived, normalizedFiles, outsideProjectFiles) {
   const output = {
     kaddo_guard: true,
     ci: true,
@@ -5532,6 +5558,9 @@ function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSigna
       included: includeArchived ? ["draft", "ready", "in-progress", "blocked", "completed", "archived"] : ["draft", "ready", "in-progress", "blocked", "completed"],
       excluded: includeArchived ? [] : ["archived"]
     },
+    // Git-root-relative → project-root-relative mapping used for matching (VS-060.1).
+    normalized_files: normalizedFiles,
+    files_outside_project: outsideProjectFiles,
     touched_files: touchedFiles.length,
     fyi_count: activeMatches.length,
     ignored_count: ignoredCount,
@@ -5580,8 +5609,16 @@ async function runGuard(opts = {}) {
   const ignores = loadIgnores(dir);
   const plugins = resolvePlugins(config.plugins ?? []);
   const mode = opts.staged ? "staged" : "head";
-  const currentFiles = await getModifiedFiles(mode);
-  const untrackedFiles = opts.staged ? [] : await getUntrackedFiles();
+  const currentFilesRaw = await getModifiedFiles(mode);
+  const gitRoot = await getGitRoot(dir);
+  const currentPairs = currentFilesRaw.map((raw) => ({
+    raw,
+    project: normalizeTouchedPathForProject(raw, gitRoot, dir)
+  }));
+  const inProjectPairs = currentPairs.filter((p2) => p2.project !== null);
+  const currentFiles = inProjectPairs.map((p2) => p2.project);
+  const outsideProjectFiles = currentPairs.filter((p2) => p2.project === null).map((p2) => p2.raw);
+  const untrackedFiles = opts.staged ? [] : (await getUntrackedFiles()).map((f) => normalizeTouchedPathForProject(f, gitRoot, dir)).filter((f) => f !== null);
   const printUntracked = () => {
     if (untrackedFiles.length === 0 || jsonMode) return;
     console.log("");
@@ -5596,6 +5633,7 @@ async function runGuard(opts = {}) {
   }
   const workspaceFiles = workspaceScan ? workspaceScan.changedFiles.map((c) => c.normalizedPath) : [];
   const touchedFiles = [.../* @__PURE__ */ new Set([...currentFiles, ...workspaceFiles])];
+  const displayTouched = [.../* @__PURE__ */ new Set([...inProjectPairs.map((p2) => p2.raw), ...workspaceFiles])];
   if (touchedFiles.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     console.log("kaddo guard: no modified files detected.");
@@ -5631,7 +5669,7 @@ async function runGuard(opts = {}) {
     const ownerMapCI = loadOwners(dir);
     const matchedDomainsCI = collectMatchedDomains(activeMatches.map((m) => m.artifact.domains));
     const affectedOwnersCI = resolveAffectedOwners(matchedDomainsCI, ownerMapCI);
-    printCIJson(dir, touchedFiles, activeMatches, alreadyIgnoredMatches.length, pluginSignals, affectedOwnersCI, workspaceScan, includeArchived);
+    printCIJson(dir, touchedFiles, activeMatches, alreadyIgnoredMatches.length, pluginSignals, affectedOwnersCI, workspaceScan, includeArchived, inProjectPairs.map((p2) => ({ raw_path: p2.raw, project_path: p2.project })), outsideProjectFiles);
     return;
   }
   if (result.silenced && pluginSignals.length === 0) {
@@ -5640,7 +5678,7 @@ async function runGuard(opts = {}) {
   }
   if (result.matches.length === 0 && pluginSignals.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
-    printHeader(touchedFiles);
+    printHeader(displayTouched);
     printOwnershipScope(includeArchived);
     console.log("  No artifact ownership matches found.");
     console.log("");
@@ -5651,7 +5689,7 @@ async function runGuard(opts = {}) {
     return;
   }
   if (workspaceScan) printWorkspaceHeader(workspaceScan);
-  printHeader(touchedFiles);
+  printHeader(displayTouched);
   printOwnershipScope(includeArchived);
   printUntracked();
   for (const match of activeMatches) {
@@ -5999,7 +6037,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path5, md) {
+function parseCapsule(id, path6, md) {
   const { data } = matter2(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -6009,7 +6047,7 @@ function parseCapsule(id, path5, md) {
   }
   return {
     id,
-    path: path5,
+    path: path6,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -6064,14 +6102,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 toPosix2(p2) {
+function toPosix3(p2) {
   return p2.replace(/\\/g, "/");
 }
 function slug(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr(a) {
-  return toPosix2(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
 }
 function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   const scope = opts.scope ?? "active";
@@ -6095,9 +6133,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path5 = layer2.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path5) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path5 });
+    const path6 = layer2.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path6) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path6 });
       presentLayers.push(layer2.id);
     }
   }
@@ -6256,14 +6294,14 @@ function loadGraphSummary(dir) {
 
 // src/core/graph-hints.ts
 var KNOWLEDGE3 = "knowledge";
-function toPosix3(p2) {
+function toPosix4(p2) {
   return p2.replace(/\\/g, "/");
 }
 function slug2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr2(a) {
-  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+  return toPosix4(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
 }
 function capabilityHeadings(dir) {
   const p2 = join(dir, KNOWLEDGE3, "product", "capabilities.md");
@@ -8007,7 +8045,7 @@ function runUnderstand() {
 }
 
 // src/core/classifier.ts
-import path4 from "path";
+import path5 from "path";
 var MIGRATION_PATTERNS = [
   /supabase\/migrations\//,
   /prisma\/migrations\//,
@@ -8046,7 +8084,7 @@ var DEP_PATTERNS = [
   /^pom\.xml$/
 ];
 function normalizePath2(p2) {
-  return p2.split(path4.sep).join("/");
+  return p2.split(path5.sep).join("/");
 }
 function matchesAny(file, patterns) {
   const normalized = normalizePath2(file);
@@ -8878,10 +8916,10 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
 var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
-  const path5 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path5)) return null;
+  const path6 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path6)) return null;
   try {
-    return parseYaml13(readFile(path5));
+    return parseYaml13(readFile(path6));
   } catch {
     return null;
   }
@@ -10486,10 +10524,10 @@ function slugify3(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path5 = join(dir, DESCRIPTOR_PATH3);
-  if (!exists(path5)) return { version: 1, modules: [] };
+  const path6 = join(dir, DESCRIPTOR_PATH3);
+  if (!exists(path6)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml14(readFile(path5));
+    const parsed = parseYaml14(readFile(path6));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -10878,6 +10916,315 @@ function runGraphExport(opts = {}) {
   outro2("Knowledge graph ready.");
 }
 
+// src/core/impact-report.ts
+import matter8 from "gray-matter";
+var BROAD_GLOB = /^[^/*]+\/\*\*$/;
+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 connectedRoadmap = 0;
+  const globCounts = /* @__PURE__ */ new Map();
+  for (const wi of wis) {
+    if (wi.codeGlobs.length > 0) withOwnership++;
+    const hasSource = Boolean(wi.sourceId) || wi.source === "roadmap";
+    if (hasSource) withSource++;
+    if (hasSource || wi.initiative) connectedRoadmap++;
+    if (wi.initiative) withInitiative++;
+    if (wi.knowledgeLevel) withLevel++;
+    for (const g2 of wi.codeGlobs) globCounts.set(g2, (globCounts.get(g2) ?? 0) + 1);
+    try {
+      const body = matter8(readFile(wi.filePath)).content;
+      if (hasSection(body, /acceptance/i)) withAcceptance++;
+      if (hasSection(body, /definition of done|^#{1,6}\s*done\b/i)) withDoD++;
+    } catch {
+    }
+  }
+  const ownedCodePaths = [...globCounts.values()].reduce((a, b) => a + b, 0);
+  const broadGlobs = [...globCounts.keys()].filter((g2) => BROAD_GLOB.test(g2)).length;
+  const ownershipOverlaps = [...globCounts.values()].filter((n) => n > 1).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;
+  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);
+  }
+  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\`.`);
+  if (total > 0 && withOwnership < total) actions.push("Add code ownership to Work Items without `code:` globs (`kaddo owners suggest`).");
+  if (total > 0 && withInitiative < total) actions.push("Add an initiative to Work Items missing one.");
+  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,
+    score,
+    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("## 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");
@@ -10899,13 +11246,20 @@ var capsuleCmd = program.command("capsule").description("Export this project as
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").action(() => {
   runCapsuleExport();
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path5) => {
-  runCapsuleAdd(path5);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path6) => {
+  runCapsuleAdd(path6);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 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.0",
+  "version": "3.23.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {