@kaddo/cli 3.16.4 → 3.17.0

package/README.md

@@ -437,6 +437,26 @@ contracts, risks, ADRs, owners — never source code or secrets); refine it with
 the capsules (warning when one looks stale). See the
 [Knowledge Capsules guide](https://kaddo.trycatch.tv/knowledge-capsules/).
 
+---
+
+### `kaddo graph export`
+
+Export the connections that already exist between your knowledge artifacts as a **lightweight,
+file-based knowledge graph** — for onboarding, impact analysis and context selection.
+
+```bash
+kaddo graph export                  # → .kaddo/graph.json + .kaddo/graph.mmd
+kaddo graph export --scope all      # include every artifact (default: active)
+kaddo graph export --format mermaid # mermaid only (or --format json)
+```
+
+Nodes come from knowledge layers, Work Items, code globs, capabilities, ADRs and Knowledge
+Capsules; edges come from front matter (`code`, `capabilities`, `decisions`, `source_id`,
+`source_initiative`) and the external registry. It never reads `src/`, never reads source code
+and never calls an LLM. `kaddo explain` and `kaddo context` show a graph **summary** once it has
+been exported (they never generate it). See the
+[Knowledge Graph Export guide](https://kaddo.trycatch.tv/knowledge-graph-export/).
+
 ## Roadmap
 
 The full knowledge loop ships today: `scan → context → agents → understand → roadmap →
@@ -478,6 +498,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.14 | Project knowledge language (`project.language: en\|es`): knowledge in your language, CLI stays English; all agents respect it |
 | v3.15 | Delivery context consistency: phase-based handoff + per-phase LLM instructions; assisted `owners suggest` (normalize/validate globs); new `ownership-agent`; guard untracked-files warning; duplicate Work Item detection |
 | v3.16 | Knowledge Capsules: `kaddo capsule export/add`, External Knowledge in context/explain, new `capsule-agent` |
+| v3.17 | Knowledge Graph Export: `kaddo graph export` (`.kaddo/graph.json` + `.mmd`, `--scope`/`--format`); graph summary in context/explain |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -680,6 +680,10 @@ var COMMAND_HELP = {
   "capsule add": {
     question: "How do I consume another system as external context?",
     next: "kaddo context (the pack now includes External Knowledge)"
+  },
+  "graph export": {
+    question: "How is my project knowledge connected?",
+    next: "Open .kaddo/graph.mmd, or run kaddo explain for a summary"
   }
 };
 function commandFooterLines(name) {
@@ -4157,8 +4161,8 @@ async function runCreate(type, opts = {}) {
     answers[question.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug2 = slugify(title);
-  const fileName = `${id}-${slug2}.md`;
+  const slug3 = slugify(title);
+  const fileName = `${id}-${slug3}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildFrontMatter(id, workItemType, level, title.trim(), answers);
   const body = buildBody(workItemType, level, title.trim(), answers, levelDef.qualityGate);
@@ -4198,8 +4202,8 @@ async function runCreateModule(dir, modType) {
     answers[q.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug2 = slugify(title);
-  const fileName = `${id}-${slug2}.md`;
+  const slug3 = slugify(title);
+  const fileName = `${id}-${slug3}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildModuleFrontMatter(id, modType, title.trim(), answers);
   const body = buildModuleBody(modType, title.trim(), answers);
@@ -4331,8 +4335,8 @@ function buildRoadmapWorkItem(opts) {
   const { id, type, level, candidate } = opts;
   const answers = opts.answers ?? {};
   const title = candidate.title.trim();
-  const slug2 = slugify(title);
-  const fileName = `${id}-${slug2}.md`;
+  const slug3 = slugify(title);
+  const fileName = `${id}-${slug3}.md`;
   const qualityGate = getLevel(level).qualityGate;
   const frontMatter2 = buildRoadmapFrontMatter(id, type, level, title, candidate, answers);
   const body = buildRoadmapBody(type, level, title, candidate, answers, qualityGate);
@@ -4480,7 +4484,8 @@ function parseArtifact(filePath, raw) {
       phase: String(data.phase ?? ""),
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
       source: data.source ? String(data.source) : "",
-      sourceId: String(data.source_id ?? "")
+      sourceId: String(data.source_id ?? ""),
+      decisions: Array.isArray(data.decisions) ? data.decisions.map(String).filter(Boolean) : []
     };
   } catch {
     return null;
@@ -5585,8 +5590,194 @@ function loadExternalCapsules(dir) {
   return out;
 }
 
-// src/core/knowledge-discovery.ts
+// src/core/graph.ts
 var KNOWLEDGE2 = "knowledge";
+function toPosix2(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);
+}
+function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
+  const scope = opts.scope ?? "active";
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = [];
+  const edgeKeys = /* @__PURE__ */ new Set();
+  const addNode = (node) => {
+    if (!nodes.has(node.id)) nodes.set(node.id, node);
+  };
+  const addEdge = (from, to, type) => {
+    const key = `${from}|${to}|${type}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push({ from, to, type });
+  };
+  const layerDocs = [
+    { id: "business:business", type: "business", label: "Business", files: ["business/business.md"] },
+    { id: "product:product", type: "product", label: "Product", files: ["product/product.md", "product/capabilities.md"] },
+    { id: "tech:tech", type: "tech", label: "Tech", files: ["tech/current-state.md", "tech/codebase.md"] },
+    { id: "delivery:delivery", type: "delivery", label: "Delivery", files: ["delivery/roadmap.md"] }
+  ];
+  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 });
+      presentLayers.push(layer2.id);
+    }
+  }
+  for (let i = 0; i < presentLayers.length - 1; i++) {
+    addEdge(presentLayers[i], presentLayers[i + 1], "informs");
+  }
+  const all = discoverKnowledge(dir);
+  const workItems = all.filter((a) => a.isWorkItem);
+  const selectedWIs = scope === "active" ? workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)) : workItems;
+  for (const wi of selectedWIs) {
+    const id = wi.id || wi.title;
+    const wiNodeId = `wi:${id}`;
+    addNode({
+      id: wiNodeId,
+      type: "work-item",
+      label: `${id} ${wi.title}`.trim(),
+      path: wi.relPath,
+      status: wi.lifecycle,
+      knowledge_level: wi.knowledgeLevel || void 0
+    });
+    for (const glob of wi.codeGlobs) {
+      const codeId = `code:${glob}`;
+      addNode({ id: codeId, type: "code-glob", label: glob });
+      addEdge(wiNodeId, codeId, "owns");
+    }
+    for (const cap of wi.capabilities) {
+      const capId = `capability:${slug(cap) || cap}`;
+      addNode({ id: capId, type: "capability", label: cap });
+      addEdge(wiNodeId, capId, "implements");
+    }
+    for (const dec of wi.decisions) {
+      const adrId = `adr:${dec}`;
+      addNode({ id: adrId, type: "decision", label: dec });
+      addEdge(wiNodeId, adrId, "depends_on");
+    }
+    if (wi.initiative) {
+      const initId = `initiative:${slug(wi.initiative) || wi.initiative}`;
+      addNode({ id: initId, type: "initiative", label: wi.initiative });
+      addEdge(wiNodeId, initId, "belongs_to");
+    }
+    if (wi.source === "roadmap" && wi.sourceId) {
+      const candId = `candidate:${wi.sourceId}`;
+      addNode({ id: candId, type: "roadmap-candidate", label: wi.sourceId });
+      addEdge(candId, wiNodeId, "materialized_as");
+    }
+  }
+  for (const adr of all.filter(isAdr)) {
+    const adrId = `adr:${adr.id || adr.title}`;
+    const referenced = nodes.has(adrId);
+    if (scope === "all" || referenced) {
+      nodes.set(adrId, {
+        id: adrId,
+        type: "decision",
+        label: `${adr.id} ${adr.title}`.trim() || adr.id || adr.title,
+        path: adr.relPath
+      });
+      for (const glob of adr.codeGlobs) {
+        const codeId = `code:${glob}`;
+        addNode({ id: codeId, type: "code-glob", label: glob });
+        addEdge(adrId, codeId, "governs");
+      }
+    }
+  }
+  const capsules = loadExternalRegistry(dir);
+  if (capsules.length > 0) {
+    const projId = `project:${slug(config.project.name) || "project"}`;
+    addNode({ id: projId, type: "project", label: config.project.name });
+    for (const cap of capsules) {
+      const capId = `capsule:${cap.id}`;
+      addNode({ id: capId, type: "knowledge-capsule", label: cap.id, path: cap.path });
+      addEdge(capId, projId, "provides_external_context");
+    }
+  }
+  return {
+    generated_at: now.toISOString(),
+    project: {
+      name: config.project.name,
+      state: config.project.state,
+      structure: config.project.structure
+    },
+    nodes: [...nodes.values()],
+    edges
+  };
+}
+var RELATIONSHIP_EDGES = /* @__PURE__ */ new Set([
+  "belongs_to",
+  "materialized_as",
+  "owns",
+  "implements",
+  "depends_on",
+  "governs",
+  "provides_external_context"
+]);
+function graphIsSparse(graph) {
+  return !graph.edges.some((e) => RELATIONSHIP_EDGES.has(e.type));
+}
+function serializeGraphJson(graph) {
+  return JSON.stringify(graph, null, 2) + "\n";
+}
+function renderGraphMermaid(graph) {
+  const safeIds = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  const safe = (id) => {
+    const existing = safeIds.get(id);
+    if (existing) return existing;
+    let base = id.replace(/[^a-zA-Z0-9]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+    if (!base) base = "n";
+    let candidate = base;
+    let i = 1;
+    while (used.has(candidate)) candidate = `${base}_${i++}`;
+    used.add(candidate);
+    safeIds.set(id, candidate);
+    return candidate;
+  };
+  const escapeLabel = (s) => s.replace(/"/g, "'");
+  const lines = ["flowchart LR"];
+  for (const node of graph.nodes) {
+    lines.push(`  ${safe(node.id)}["${escapeLabel(node.label)}"]`);
+  }
+  if (graph.edges.length > 0) lines.push("");
+  for (const edge of graph.edges) {
+    lines.push(`  ${safe(edge.from)} -->|${edge.type}| ${safe(edge.to)}`);
+  }
+  return lines.join("\n") + "\n";
+}
+var ACTIVE_WI_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
+function loadGraphSummary(dir) {
+  const p2 = join(dir, ".kaddo", "graph.json");
+  if (!exists(p2)) return null;
+  try {
+    const graph = JSON.parse(readFile(p2));
+    const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+    const edges = Array.isArray(graph.edges) ? graph.edges : [];
+    const activeWiIds = new Set(
+      nodes.filter((n) => n.type === "work-item" && (!n.status || ACTIVE_WI_STATES.has(n.status))).map((n) => n.id)
+    );
+    const connected = new Set(
+      edges.filter((e) => e.type === "owns" && activeWiIds.has(e.from)).map((e) => e.from)
+    );
+    return {
+      generatedAt: String(graph.generated_at ?? ""),
+      nodes: nodes.length,
+      edges: edges.length,
+      activeWorkItemsConnectedToCode: connected.size
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/core/knowledge-discovery.ts
+var KNOWLEDGE3 = "knowledge";
 var CONSOLIDATED_TYPE = {
   Business: "business",
   Product: "product",
@@ -5628,10 +5819,10 @@ function layerForType(type) {
 }
 function layerFromPath(filePath) {
   const p2 = filePath.replace(/\\/g, "/");
-  if (p2.includes(`/${KNOWLEDGE2}/business/`)) return "Business";
-  if (p2.includes(`/${KNOWLEDGE2}/product/`)) return "Product";
-  if (p2.includes(`/${KNOWLEDGE2}/tech/`)) return "Tech";
-  if (p2.includes(`/${KNOWLEDGE2}/delivery/`)) return "Delivery";
+  if (p2.includes(`/${KNOWLEDGE3}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE3}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE3}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE3}/delivery/`)) return "Delivery";
   return null;
 }
 function basename(p2) {
@@ -5644,7 +5835,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE2);
+  const archDir = join(dir, KNOWLEDGE3);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -5666,7 +5857,7 @@ function discoverLayers(dir) {
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE2, "tech", "decisions"))) acc.Tech.structured = true;
+  if (existsDirWithMd(join(dir, KNOWLEDGE3, "tech", "decisions"))) acc.Tech.structured = true;
   return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
     layer: layer2,
     status: statusFor(layer2, acc[layer2]),
@@ -5915,6 +6106,7 @@ function buildProjectExplanation(dir) {
     domains,
     duplicateWorkItems,
     externalCapsules: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
     layers,
     roadmap,
     mappedModules,
@@ -6054,6 +6246,13 @@ function renderExplanationHuman(exp) {
     }
     lines.push("");
   }
+  if (exp.graph) {
+    lines.push("## Knowledge Graph");
+    lines.push(`- Nodes: ${exp.graph.nodes}`);
+    lines.push(`- Edges: ${exp.graph.edges}`);
+    if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
+    lines.push("");
+  }
   if (exp.missingKnowledge.length > 0) {
     lines.push("## Missing Knowledge");
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
@@ -6461,6 +6660,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     phase,
     deliveryMix,
     external: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -6626,6 +6826,18 @@ function renderContextPack(pack) {
       parts.push(lines.join("\n") + "\n");
     }
   }
+  if (pack.graph) {
+    parts.push("## Knowledge Graph\n");
+    parts.push(
+      [
+        "- Available: yes",
+        `- Nodes: ${pack.graph.nodes}`,
+        `- Edges: ${pack.graph.edges}`,
+        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`
+      ].join("\n") + "\n"
+    );
+    parts.push("Full graph: `.kaddo/graph.json` / `.kaddo/graph.mmd` (run `kaddo graph export` to refresh).\n");
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -8067,7 +8279,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE3 = `---
+var KNOWLEDGE4 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -9077,7 +9289,7 @@ var KADDO_TEMPLATES = [
     description: "What is true about the product right now.",
     whenToUse: "Created by `kaddo init`; keep it current as the product evolves.",
     relatedCommand: "kaddo init",
-    content: KNOWLEDGE3
+    content: KNOWLEDGE4
   },
   // business / product (bootstrap — consolidated, minimal)
   {
@@ -9729,7 +9941,7 @@ async function runBootstrap(dir = cwd()) {
 }
 
 // src/commands/capsule.ts
-function slug(s) {
+function slug2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 }
 function runCapsuleExport() {
@@ -9737,7 +9949,7 @@ function runCapsuleExport() {
   const config = requireConfig(dir);
   intro2("kaddo capsule export");
   const capsule = buildCapsule(dir, config);
-  const name = slug(config.project.name);
+  const name = slug2(config.project.name);
   const mdPath = join(".kaddo", "exports", `${name}.capsule.md`);
   const jsonPath = join(".kaddo", "exports", `${name}.capsule.json`);
   writeFile(join(dir, mdPath), renderCapsuleMarkdown(capsule));
@@ -9773,6 +9985,39 @@ function runCapsuleAdd(srcPath) {
   outro2("External capsule registered.");
 }
 
+// src/commands/graph.ts
+function runGraphExport(opts = {}) {
+  const dir = cwd();
+  const config = requireConfig(dir);
+  intro2("kaddo graph export");
+  const scope = opts.scope === "all" ? "all" : "active";
+  const format = opts.format;
+  const writeJson = format !== "mermaid";
+  const writeMermaid = format !== "json";
+  const graph = buildGraph(dir, config, { scope });
+  const written = [];
+  if (writeJson) {
+    const rel = join(".kaddo", "graph.json");
+    writeFile(join(dir, rel), serializeGraphJson(graph));
+    written.push(rel.replace(/\\/g, "/"));
+  }
+  if (writeMermaid) {
+    const rel = join(".kaddo", "graph.mmd");
+    writeFile(join(dir, rel), renderGraphMermaid(graph));
+    written.push(rel.replace(/\\/g, "/"));
+  }
+  if (graphIsSparse(graph)) {
+    log2.warn("Knowledge graph exported with limited relationships.");
+    log2.info("Tip: add `code`, `capabilities`, `decisions` or `source_id` front matter to improve graph quality.");
+  } else {
+    log2.success("Knowledge graph exported.");
+  }
+  log2.info(`Scope: ${scope} \xB7 Nodes: ${graph.nodes.length} \xB7 Edges: ${graph.edges.length}`);
+  for (const f of written) log2.info(`- ${f}`);
+  printCommandFooter("graph export");
+  outro2("Knowledge graph ready.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -9797,6 +10042,10 @@ capsuleCmd.command("export").description("Write a Knowledge Capsule about this p
 capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path5) => {
   runCapsuleAdd(path5);
 });
+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);
+});
 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) => {
   await runGuard(opts);
 });

package/package.json

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