@kaddo/mcp 3.23.0 → 3.23.2

package/dist/index.js

@@ -2087,7 +2087,11 @@ function renderExplanationAgent(exp) {
 }
 
 // ../cli/src/core/impact-report.ts
-var BROAD_GLOB = /^[^/*]+\/\*\*$/;
+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";
@@ -2098,6 +2102,8 @@ 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 resolvedScope = opts.scope ?? "all";
+  const scopeSource = opts.scopeSource ?? (opts.scope ? "explicit" : "default");
   const exp = buildProjectExplanation(dir);
   const wis = discoverWorkItems(dir);
   const total = wis.length;
@@ -2107,40 +2113,74 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   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++;
-    for (const g2 of wi.codeGlobs) globCounts.set(g2, (globCounts.get(g2) ?? 0) + 1);
+    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 = matter6(readFile(wi.filePath)).content;
-      if (hasSection(body, /acceptance/i)) withAcceptance++;
-      if (hasSection(body, /definition of done|^#{1,6}\s*done\b/i)) withDoD++;
+      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) => 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: "" };
+  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." });
     }
-  } 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 };
+  }
+  const ownershipOverlaps = gaps.ownership_overlaps.length;
+  let g;
+  const config = loadConfig(dir);
+  if (config) {
+    const graph = buildGraph(dir, config, { scope: resolvedScope }, 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: "n/a", scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
+    g = { available: false, scope: resolvedScope, 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;
@@ -2209,6 +2249,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
     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;
@@ -2220,13 +2261,34 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
     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.");
+  else if (g.scope === "active" && g.quality === "empty") actions.push("Run `kaddo impact --scope all` to measure accumulated knowledge impact.");
   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.");
+  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.");
@@ -2241,6 +2303,8 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
     generated_at: now.toISOString(),
     project: exp.project.name,
     scope: g.scope,
+    default_scope: "all",
+    scope_source: scopeSource,
     executive_summary: summary,
     knowledge_health,
     knowledge_coverage,
@@ -2278,7 +2342,9 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       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
   };
 }
@@ -2293,6 +2359,11 @@ function renderImpactMarkdown(r) {
   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");
+  if (r.scope_source === "default") {
+    L.push("Scope note: Impact reports use `all` by default to measure accumulated knowledge impact.");
+  } else if (r.scope === "active" && r.graph_quality.available === false) {
+    L.push("Tip: Run `kaddo impact --scope all` to inspect accumulated knowledge impact.");
+  }
   L.push("");
   L.push("## Executive Summary", "");
   for (const s2 of r.executive_summary) L.push(`- ${s2}`);
@@ -2349,6 +2420,9 @@ function renderImpactMarkdown(r) {
     L.push(`- Hints: ${gq.hints}`);
     if (gq.reason) L.push(`- Reason: ${gq.reason}`);
     if (gq.last_exported) L.push(`- Last exported: ${gq.last_exported}`);
+    if (gq.scope === "active" && gq.quality === "empty") {
+      L.push("- Tip: Run `kaddo impact --scope all` to inspect accumulated knowledge impact.");
+    }
   } else {
     L.push("- Graph data not available.");
     L.push(`- Tip: ${r.graph_quality.suggestion}`);
@@ -2367,6 +2441,58 @@ function renderImpactMarkdown(r) {
   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("");
@@ -2586,7 +2712,7 @@ var RESOURCES = [
       if (!hasKnowledge(root)) {
         return text("kaddo://impact-report", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
       }
-      return [{ uri: "kaddo://impact-report", text: renderImpactMarkdown(buildImpactReport(root, { scope: "all" })), mimeType: "text/markdown" }];
+      return [{ uri: "kaddo://impact-report", text: renderImpactMarkdown(buildImpactReport(root, { scope: "all", scopeSource: "default" })), mimeType: "text/markdown" }];
     }
   }
 ];
@@ -3354,7 +3480,7 @@ function generateImpactReport(root, opts = {}) {
   requireConfig(root);
   requireKnowledge(root);
   const format = opts.format ?? "markdown";
-  const report = buildImpactReport(root, { scope: opts.scope ?? "all" });
+  const report = buildImpactReport(root, { scope: opts.scope ?? "all", scopeSource: opts.scope ? "explicit" : "default" });
   const content = format === "json" ? serializeImpactJson(report) : renderImpactMarkdown(report);
   const out = opts.output ?? `.kaddo/reports/impact-report.${format === "json" ? "json" : "md"}`;
   writeDerived(root, out, content);

package/package.json

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