@kaddo/cli 3.23.0 → 3.23.1

package/README.md

@@ -511,6 +511,7 @@ create --from roadmap → owners → guard → explain`.
 | 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

@@ -10918,7 +10918,11 @@ function runGraphExport(opts = {}) {
 
 // src/core/impact-report.ts
 import matter8 from "gray-matter";
-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";
@@ -10938,26 +10942,66 @@ 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 = matter8(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;
+  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);
@@ -11040,6 +11084,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;
@@ -11051,13 +11096,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.");
   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.");
@@ -11109,7 +11175,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
   };
 }
@@ -11198,6 +11266,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("");

package/package.json

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