@kaddo/cli 3.23.0 → 3.23.2

package/README.md

@@ -511,6 +511,8 @@ 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 |
+| v3.23.2 | Impact report defaults to `all` scope (accumulated impact), graph built in memory; `--scope active`; `scope_source`/`default_scope` in JSON |
 
 **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";
@@ -10929,6 +10933,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;
@@ -10938,40 +10944,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 = 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;
-  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;
@@ -11040,6 +11080,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 +11092,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.");
@@ -11072,6 +11134,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,
@@ -11109,7 +11173,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
   };
 }
@@ -11124,6 +11190,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}`);
@@ -11180,6 +11251,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}`);
@@ -11198,6 +11272,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("");
@@ -11211,7 +11337,8 @@ function serializeImpactJson(r) {
 function runReportImpact(opts = {}) {
   const dir = cwd();
   requireConfig(dir);
-  const report = buildImpactReport(dir);
+  const scope = opts.scope === "active" ? "active" : opts.scope === "all" ? "all" : void 0;
+  const report = buildImpactReport(dir, { scope });
   const content = opts.json ? serializeImpactJson(report) : renderImpactMarkdown(report);
   if (opts.output) {
     intro2("kaddo report impact");
@@ -11254,10 +11381,10 @@ graphCmd.command("export").description("Write the knowledge graph to .kaddo/grap
   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) => {
+reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").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) => {
+program.command("impact").description("Alias for `kaddo report impact`").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").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) => {

package/package.json

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