@kaddo/cli 3.21.0 → 3.22.0

package/README.md

@@ -508,6 +508,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.19 | Read-only MCP server `@kaddo/mcp` (resources, tools, prompts over stdio) |
 | 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`) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -5524,10 +5524,14 @@ async function offerIgnore(dir, match) {
   log2.success(`${id} added to .kaddo/ignores.yml`);
   return true;
 }
-function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace) {
+function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace, includeArchived) {
   const output = {
     kaddo_guard: true,
     ci: true,
+    ownership_scope: {
+      included: includeArchived ? ["draft", "ready", "in-progress", "blocked", "completed", "archived"] : ["draft", "ready", "in-progress", "blocked", "completed"],
+      excluded: includeArchived ? [] : ["archived"]
+    },
     touched_files: touchedFiles.length,
     fyi_count: activeMatches.length,
     ignored_count: ignoredCount,
@@ -5556,6 +5560,12 @@ function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSigna
   }
   console.log(JSON.stringify(output, null, 2));
 }
+function printOwnershipScope(includeArchived) {
+  console.log("Ownership scope:");
+  console.log("- Active and completed Work Items");
+  console.log(includeArchived ? "- Archived Work Items included (--include-archived)" : "- Archived Work Items excluded");
+  console.log("");
+}
 async function runGuard(opts = {}) {
   const dir = cwd();
   const interactive = opts.interactive !== false && !opts.ci && !opts.json;
@@ -5597,7 +5607,10 @@ async function runGuard(opts = {}) {
     console.log("kaddo guard: no knowledge/ directory found. Run `kaddo init` first.");
     return;
   }
-  const artifacts = discoverKnowledge(dir);
+  const includeArchived = opts.includeArchived === true;
+  const artifacts = discoverKnowledge(dir).filter(
+    (a) => !(a.isWorkItem && a.lifecycle === "archived" && !includeArchived)
+  );
   const result = analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership);
   const pluginSignals = runPlugins(plugins, currentFiles, (filePath) => {
     const abs = join(dir, filePath);
@@ -5618,7 +5631,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);
+    printCIJson(dir, touchedFiles, activeMatches, alreadyIgnoredMatches.length, pluginSignals, affectedOwnersCI, workspaceScan, includeArchived);
     return;
   }
   if (result.silenced && pluginSignals.length === 0) {
@@ -5628,12 +5641,18 @@ async function runGuard(opts = {}) {
   if (result.matches.length === 0 && pluginSignals.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     printHeader(touchedFiles);
+    printOwnershipScope(includeArchived);
     console.log("  No artifact ownership matches found.");
+    console.log("");
+    console.log("Note:");
+    console.log("Guard checks ownership from active and completed Work Items.");
+    console.log("Run `kaddo explain` to inspect ownership coverage.");
     printUntracked();
     return;
   }
   if (workspaceScan) printWorkspaceHeader(workspaceScan);
   printHeader(touchedFiles);
+  printOwnershipScope(includeArchived);
   printUntracked();
   for (const match of activeMatches) {
     printFYI(match, dir);
@@ -6040,6 +6059,11 @@ function loadExternalCapsules(dir) {
 
 // src/core/graph.ts
 var KNOWLEDGE2 = "knowledge";
+var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
+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) {
   return p2.replace(/\\/g, "/");
 }
@@ -6082,7 +6106,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   }
   const all = discoverKnowledge(dir);
   const workItems = all.filter((a) => a.isWorkItem);
-  const selectedWIs = scope === "active" ? workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)) : workItems;
+  const { included, excluded } = scopeStatuses(scope);
+  const includedSet = new Set(included);
+  const activeWICount = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)).length;
+  const selectedWIs = workItems.filter((a) => a.lifecycle && includedSet.has(a.lifecycle));
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     const wiNodeId = `wi:${id}`;
@@ -6152,6 +6179,7 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
   }
+  const scopeReason = scope === "all" ? "All supported Work Item statuses are included." : activeWICount === 0 ? "No active Work Items found. Completed Work Items are excluded from active scope." : "Active Work Items only; completed and archived are excluded.";
   return {
     generated_at: now.toISOString(),
     project: {
@@ -6159,6 +6187,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       state: config.project.state,
       structure: config.project.structure
     },
+    scope,
+    scope_reason: scopeReason,
+    included_statuses: included,
+    excluded_statuses: excluded,
     nodes: [...nodes.values()],
     edges
   };
@@ -6206,8 +6238,13 @@ function loadGraphSummary(dir) {
     const connected = new Set(
       edges.filter((e) => e.type === "owns" && activeWiIds.has(e.from)).map((e) => e.from)
     );
+    const scope = graph.scope === "all" ? "all" : "active";
     return {
       generatedAt: String(graph.generated_at ?? ""),
+      scope,
+      scopeReason: String(graph.scope_reason ?? ""),
+      includedStatuses: Array.isArray(graph.included_statuses) ? graph.included_statuses : [],
+      excludedStatuses: Array.isArray(graph.excluded_statuses) ? graph.excluded_statuses : [],
       nodes: nodes.length,
       edges: edges.length,
       activeWorkItemsConnectedToCode: connected.size
@@ -6359,6 +6396,8 @@ function buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
   const quality = assessQuality(nodes, relationshipEdges, hints.length);
   return {
     generated_at: now.toISOString(),
+    scope: graph.scope,
+    scope_reason: graph.scope_reason,
     quality,
     summary: { nodes, edges: graph.edges.length, hints: hints.length },
     metrics,
@@ -6394,13 +6433,23 @@ function renderGraphHintsMarkdown(report) {
   lines.push("");
   lines.push("## Summary");
   lines.push("");
+  lines.push(`- Scope: ${report.scope} \u2014 ${report.scope_reason}`);
   lines.push(`- Relationship quality: ${report.quality} \u2014 ${QUALITY_NOTE[report.quality]}`);
   lines.push(`- Nodes: ${report.summary.nodes}`);
   lines.push(`- Edges: ${report.summary.edges}`);
   lines.push(`- Hints: ${report.summary.hints}`);
   lines.push("");
   if (report.hints.length === 0) {
-    lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    if (report.quality === "empty") {
+      lines.push("No active relationship hints were generated.");
+      lines.push("");
+      lines.push(`The graph is ${report.quality} for the **${report.scope}** scope \u2014 ${report.scope_reason}`);
+      if (report.scope !== "all") {
+        lines.push("Run `kaddo graph export --scope all` to inspect completed Work Items and historical relationships.");
+      }
+    } else {
+      lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    }
     lines.push("");
     return lines.join("\n");
   }
@@ -6436,6 +6485,8 @@ function loadGraphHints(dir) {
     const report = JSON.parse(readFile(p2));
     const hints = Array.isArray(report.hints) ? report.hints : [];
     return {
+      scope: String(report.scope ?? "active"),
+      scopeReason: String(report.scope_reason ?? ""),
       quality: report.quality ?? "empty",
       totalHints: hints.length,
       activeWorkItemHints: hints.filter((h) => h.artifact_type === "work-item").length,
@@ -6959,13 +7010,18 @@ function renderExplanationHuman(exp) {
   }
   if (exp.graph) {
     lines.push("## Knowledge Graph");
+    lines.push(`- Scope: ${exp.graph.scope}`);
     lines.push(`- Nodes: ${exp.graph.nodes}`);
     lines.push(`- Edges: ${exp.graph.edges}`);
     if (exp.graphHints) {
       lines.push(`- Quality: ${exp.graphHints.quality}`);
       lines.push(`- Hints: ${exp.graphHints.totalHints}`);
     }
+    if (exp.graph.scopeReason) lines.push(`- Reason: ${exp.graph.scopeReason}`);
     if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
+    if (exp.graph.scope === "active" && exp.graphHints?.quality === "empty") {
+      lines.push("- Tip: Run `kaddo graph export --scope all` to include completed Work Items");
+    }
     lines.push("");
   }
   if (exp.skills.total > 0) {
@@ -7557,9 +7613,12 @@ function renderContextPack(pack) {
     parts.push(
       [
         "- Available: yes",
+        `- Scope: ${pack.graph.scope}`,
         `- Nodes: ${pack.graph.nodes}`,
         `- Edges: ${pack.graph.edges}`,
-        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`
+        ...pack.graphHints ? [`- Quality: ${pack.graphHints.quality}`] : [],
+        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`,
+        ...pack.graph.scopeReason ? [`- Reason: ${pack.graph.scopeReason}`] : []
       ].join("\n") + "\n"
     );
     parts.push("Full graph: `.kaddo/graph.json` / `.kaddo/graph.mmd` (run `kaddo graph export` to refresh).\n");
@@ -10797,9 +10856,15 @@ function runGraphExport(opts = {}) {
   writeFile(join(dir, ".kaddo", "graph-hints.md"), renderGraphHintsMarkdown(hints));
   writeFile(join(dir, ".kaddo", "graph-hints.json"), serializeGraphHintsJson(hints));
   written.push(".kaddo/graph-hints.md", ".kaddo/graph-hints.json");
-  log2.success("Knowledge graph exported.");
+  log2.success(`Knowledge graph exported with ${scope} scope.`);
   log2.info(`Scope: ${scope} \xB7 Nodes: ${graph.nodes.length} \xB7 Edges: ${graph.edges.length}`);
   log2.info(`Relationship quality: ${hints.quality}`);
+  const hasWorkItemNodes = graph.nodes.some((n) => n.type === "work-item");
+  if (scope === "active" && !hasWorkItemNodes) {
+    log2.warn("No active Work Items found.");
+    log2.info("The active graph only includes knowledge layers.");
+    log2.info("Run `kaddo graph export --scope all` to include completed Work Items.");
+  }
   if (hints.hints.length > 0) {
     const shown = hints.hints.slice(0, 5);
     log2.warn(`${hints.hints.length} metadata hint(s) available:`);
@@ -10841,7 +10906,7 @@ 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);
 });
-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)").action(async (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);
 });
 var ignoreCmd = program.command("ignore").description("Manage guard ignore list");

package/package.json

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