@kaddo/cli 3.16.5 → 3.18.0

package/README.md

@@ -437,6 +437,31 @@ 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).
+
+Every export also rates **relationship quality** and writes non-blocking metadata hints
+(`.kaddo/graph-hints.md` + `.json`) — detecting active Work Items without `code`/`capabilities`,
+ADRs without governed `code`, capabilities/capsules with no Work Item link, and more. The
+`graph-agent` turns those hints into precise front matter you confirm and apply. 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 +503,8 @@ 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 |
+| v3.18 | Graph relationship quality & metadata hints: `graph-hints.md`/`.json`, quality levels, `graph-agent`; hints in context/explain/understand |
 
 **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) {
@@ -1648,6 +1652,19 @@ var RESPONSIBILITY_MATRIX = {
     ],
     next: ["kaddo capsule export"]
   },
+  "graph-agent": {
+    agent: "graph-agent",
+    responsibleFor: ["Reviewing graph hints", "Proposing precise relationship front matter"],
+    produces: ["proposed front matter (code/capabilities/decisions/source/capsules)"],
+    canSuggest: ["kaddo graph export", "kaddo owners suggest"],
+    cannotSuggest: [
+      "code",
+      "git",
+      "modifying files without confirmation",
+      "inventing relationships"
+    ],
+    next: ["kaddo graph export"]
+  },
   "ownership-agent": {
     agent: "ownership-agent",
     responsibleFor: ["Precise code: ownership for Work Items and artifacts"],
@@ -3203,6 +3220,74 @@ edit the roadmap yourself).
 - Duplicates, overlaps and dependencies are flagged.
 - The response ends with a human-decision handoff \u2014 no agent is auto-executed.
 `;
+var GRAPH_AGENT = `# Graph Agent
+
+## Role
+
+You are the Kaddo Graph Agent. Your job is to review the **graph hints** produced by
+\`kaddo graph export\` and propose **precise relationship front matter** so the knowledge graph
+becomes more connected and useful.
+
+You do not write code, you do not modify files, and you never run Git. You propose; the human
+confirms and edits the artifact front matter, then re-runs \`kaddo graph export\`.
+
+## When to Use
+
+Use this agent when \`kaddo graph export\` reports relationship quality \`partial\`, \`sparse\` or
+\`empty\`, or when \`kaddo understand\` recommends reviewing graph hints during Active Delivery.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\`, \`.kaddo/graph.json\` and \`.kaddo/graph-hints.md\` as the primary
+inputs, plus the Work Items under \`knowledge/delivery/work-items/\`, the ADRs under
+\`knowledge/tech/decisions/\` and \`knowledge/product/capabilities.md\` when they exist.
+
+## Expected Output
+
+For each hint, a concrete front matter proposal for the affected artifact, e.g.:
+
+\`\`\`yaml
+code:
+  - src/cli/**
+capabilities:
+  - task-management
+decisions:
+  - ADR-001
+\`\`\`
+
+## Instructions
+
+1. Work through the hints in \`.kaddo/graph-hints.md\` one artifact at a time.
+2. Propose only relationships you can justify from existing knowledge \u2014 never invent paths,
+   capabilities, ADRs or capsules.
+3. Prefer narrow, accurate values (e.g. \`src/payments/**\`, not \`src/**\`).
+4. Mark uncertain proposals explicitly and ask the human to confirm.
+5. Tell the human to apply the front matter and re-run \`kaddo graph export\` to verify.
+
+## Constraints
+
+- Do **not** modify files \u2014 propose front matter for the human to apply.
+- Do **not** invent relationships, paths or IDs.
+- Do **not** read the full source tree; rely on declared knowledge and the inventory.
+- Do **not** run Git or make commits.
+
+## Output Format
+
+Per artifact: the artifact id, the proposed front matter block, and a one-line reason. End with a
+note to re-run \`kaddo graph export\`.
+
+## Where to Save the Result
+
+Nothing is saved automatically. The human edits the affected artifact front matter (Work Items,
+ADRs) and re-runs \`kaddo graph export\`.
+
+## Quality Checklist
+
+- Every proposal maps to a real artifact, path, capability, ADR or capsule.
+- Globs are narrow and accurate; uncertainty is marked.
+- No files were modified; no Git was run.
+- The human is asked to confirm and re-export the graph.
+`;
 var AGENT_PROMPTS = [
   { fileName: "capability-agent.md", content: CAPABILITY_AGENT },
   { fileName: "architecture-agent.md", content: ARCHITECTURE_AGENT },
@@ -3226,7 +3311,9 @@ var AGENT_PROMPTS = [
   // Ownership proposals (precise code: globs — VS-052)
   { fileName: "ownership-agent.md", content: OWNERSHIP_AGENT },
   // Knowledge Capsule refinement (external context — VS-054)
-  { fileName: "capsule-agent.md", content: CAPSULE_AGENT }
+  { fileName: "capsule-agent.md", content: CAPSULE_AGENT },
+  // Graph relationship quality (metadata hints → precise front matter — VS-056)
+  { fileName: "graph-agent.md", content: GRAPH_AGENT }
   // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
 ].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
@@ -3242,7 +3329,8 @@ var AGENT_GROUPS = {
     "standards-agent.md",
     "module-design-agent.md",
     "adr-agent.md",
-    "capsule-agent.md"
+    "capsule-agent.md",
+    "graph-agent.md"
   ],
   delivery: [
     "backlog-agent.md",
@@ -3387,7 +3475,8 @@ var agentReadme = {
     "- `standards-agent.md` \u2014 propose lightweight coding/docs/architecture standards.",
     "- `stack-agent.md` \u2014 document technologies and stack decisions.",
     "- `module-design-agent.md` \u2014 document the design of a mapped module.",
-    "- `capsule-agent.md` \u2014 refine a Knowledge Capsule for external sharing (no secrets/source)."
+    "- `capsule-agent.md` \u2014 refine a Knowledge Capsule for external sharing (no secrets/source).",
+    "- `graph-agent.md` \u2014 review `kaddo graph export` hints and propose precise relationship front matter."
   ].join("\n")
 };
 var agentFiles = AGENT_PROMPTS.map((a) => ({
@@ -4157,8 +4246,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 slug4 = slugify(title);
+  const fileName = `${id}-${slug4}.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 +4287,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 slug4 = slugify(title);
+  const fileName = `${id}-${slug4}.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 +4420,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 slug4 = slugify(title);
+  const fileName = `${id}-${slug4}.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 +4569,9 @@ 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) : [],
+      capsules: Array.isArray(data.capsules) ? data.capsules.map(String).filter(Boolean) : []
     };
   } catch {
     return null;
@@ -5585,8 +5676,416 @@ 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");
+      for (const wi of selectedWIs) {
+        if (wi.capsules.includes(cap.id)) {
+          addEdge(`wi:${wi.id || wi.title}`, capId, "uses_external_knowledge");
+        }
+      }
+    }
+  }
+  return {
+    generated_at: now.toISOString(),
+    project: {
+      name: config.project.name,
+      state: config.project.state,
+      structure: config.project.structure
+    },
+    nodes: [...nodes.values()],
+    edges
+  };
+}
+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/graph-hints.ts
+var KNOWLEDGE3 = "knowledge";
+function toPosix3(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function slug2(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isAdr2(a) {
+  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+}
+function capabilityHeadings(dir) {
+  const p2 = join(dir, KNOWLEDGE3, "product", "capabilities.md");
+  if (!exists(p2)) return [];
+  return readFile(p2).split(/\r?\n/).map((l) => l.match(/^#{2,3}\s+(.+?)\s*$/)).filter((m) => Boolean(m)).map((m) => m[1].trim()).filter((h) => !/^(summary|resumen|overview|capabilities|capacidades)$/i.test(h));
+}
+function humanMissing(field) {
+  switch (field) {
+    case "code":
+      return "code ownership";
+    case "capabilities":
+      return "linked capability";
+    case "decisions":
+      return "linked decision";
+    case "source":
+      return "roadmap link";
+    default:
+      return field;
+  }
+}
+function buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
+  const artifacts = discoverKnowledge(dir);
+  const workItems = artifacts.filter((a) => a.isWorkItem);
+  const activeWIs = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle));
+  const adrs = artifacts.filter(isAdr2);
+  const capsules = loadExternalRegistry(dir);
+  const hints = [];
+  const referencedCapabilitySlugs = new Set(
+    workItems.flatMap((w) => w.capabilities.map((c) => slug2(c)))
+  );
+  const referencedCapsuleIds = new Set(workItems.flatMap((w) => w.capsules.map((c) => c)));
+  let activeWithoutCode = 0;
+  let activeWithoutCapabilities = 0;
+  let wisWithoutSource = 0;
+  for (const wi of activeWIs) {
+    const id = wi.id || wi.title;
+    const missing = [];
+    const suggested = {};
+    if (wi.codeGlobs.length === 0) {
+      missing.push("code");
+      suggested.code = ["src/<area>/**"];
+      activeWithoutCode++;
+    }
+    if (wi.capabilities.length === 0) {
+      missing.push("capabilities");
+      suggested.capabilities = ["<capability>"];
+      activeWithoutCapabilities++;
+    }
+    if (wi.decisions.length === 0) {
+      missing.push("decisions");
+      suggested.decisions = ["ADR-XXX"];
+    }
+    const hasSource = Boolean(wi.sourceId) || Boolean(wi.initiative);
+    if (!hasSource) {
+      missing.push("source");
+      wisWithoutSource++;
+    }
+    if (missing.length === 0) continue;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "work-item",
+      path: wi.relPath,
+      severity: "info",
+      missing,
+      reason: "Active Work Item has limited graph relationships.",
+      message: `${id} has no ${missing.map(humanMissing).join(", ")}.`,
+      suggested_front_matter: Object.keys(suggested).length > 0 ? suggested : void 0
+    });
+  }
+  let adrsWithoutCode = 0;
+  for (const adr of adrs) {
+    if (adr.codeGlobs.length > 0) continue;
+    adrsWithoutCode++;
+    const id = adr.id || adr.title;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "decision",
+      path: adr.relPath,
+      severity: "info",
+      missing: ["code"],
+      reason: "This ADR defines technical decisions but does not declare which paths it governs.",
+      message: `${id} has no governed code paths.`,
+      suggested_front_matter: { code: ["<path/to/code>"] }
+    });
+  }
+  for (const cap of capabilityHeadings(dir)) {
+    if (referencedCapabilitySlugs.has(slug2(cap))) continue;
+    hints.push({
+      artifact_id: cap,
+      artifact_type: "capability",
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This capability is declared but no Work Item references it yet.",
+      message: `Capability "${cap}" is not linked to any Work Item.`
+    });
+  }
+  let capsulesWithoutWi = 0;
+  for (const cap of capsules) {
+    if (referencedCapsuleIds.has(cap.id)) continue;
+    capsulesWithoutWi++;
+    hints.push({
+      artifact_id: cap.id,
+      artifact_type: "knowledge-capsule",
+      path: cap.path,
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This Knowledge Capsule is available but no Work Item declares `capsules:` for it.",
+      message: `Knowledge Capsule "${cap.id}" is not linked to any Work Item.`
+    });
+  }
+  const inEdge = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    inEdge.add(e.from);
+    inEdge.add(e.to);
+  }
+  const nodes = graph.nodes.length;
+  const connected = graph.nodes.filter((n) => inEdge.has(n.id)).length;
+  const relationshipEdges = graph.edges.filter((e) => e.type !== "informs").length;
+  const metrics = {
+    nodes_count: nodes,
+    edges_count: graph.edges.length,
+    connected_nodes_count: connected,
+    isolated_nodes_count: nodes - connected,
+    active_work_items_without_code: activeWithoutCode,
+    active_work_items_without_capabilities: activeWithoutCapabilities,
+    work_items_without_source: wisWithoutSource,
+    adrs_without_code: adrsWithoutCode,
+    capsules_without_related_work_items: capsulesWithoutWi
+  };
+  const quality = assessQuality(nodes, relationshipEdges, hints.length);
+  return {
+    generated_at: now.toISOString(),
+    quality,
+    summary: { nodes, edges: graph.edges.length, hints: hints.length },
+    metrics,
+    hints
+  };
+}
+function assessQuality(nodes, relationshipEdges, hintCount) {
+  if (nodes === 0 || relationshipEdges === 0) return "empty";
+  if (relationshipEdges / nodes < 0.25) return "sparse";
+  if (hintCount > 0) return "partial";
+  return "good";
+}
+var QUALITY_NOTE = {
+  good: "Most active artifacts have meaningful relationships.",
+  partial: "Some active artifacts have missing relationship metadata.",
+  sparse: "The graph has many nodes but few meaningful edges.",
+  empty: "The graph has almost no relationships."
+};
+function yamlBlock(fm) {
+  const lines = ["```yaml"];
+  for (const [k, vals] of Object.entries(fm)) {
+    lines.push(`${k}:`);
+    for (const v of vals) lines.push(`  - ${v}`);
+  }
+  lines.push("```");
+  return lines;
+}
+function renderGraphHintsMarkdown(report) {
+  const lines = [];
+  lines.push("# Kaddo Graph Hints");
+  lines.push("");
+  lines.push("Generated by `kaddo graph export`. Suggestions only \u2014 Kaddo never edits your artifacts.");
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  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}");
+    lines.push("");
+    return lines.join("\n");
+  }
+  lines.push("## Hints");
+  lines.push("");
+  for (const h of report.hints) {
+    lines.push(`### ${h.artifact_id}${h.path ? ` \u2014 \`${h.path}\`` : ""}`);
+    lines.push("");
+    lines.push("Missing metadata:");
+    lines.push("");
+    for (const m of h.missing) lines.push(`- \`${m}\``);
+    lines.push("");
+    if (h.suggested_front_matter) {
+      lines.push("Suggested front matter:");
+      lines.push("");
+      lines.push(...yamlBlock(h.suggested_front_matter));
+      lines.push("");
+    }
+    lines.push(`Reason: ${h.reason}`);
+    lines.push("");
+  }
+  lines.push("> Use the `graph-agent` to turn these hints into precise front matter \u2014 you confirm and apply.");
+  lines.push("");
+  return lines.join("\n");
+}
+function serializeGraphHintsJson(report) {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+function loadGraphHints(dir) {
+  const p2 = join(dir, ".kaddo", "graph-hints.json");
+  if (!exists(p2)) return null;
+  try {
+    const report = JSON.parse(readFile(p2));
+    const hints = Array.isArray(report.hints) ? report.hints : [];
+    return {
+      quality: report.quality ?? "empty",
+      totalHints: hints.length,
+      activeWorkItemHints: hints.filter((h) => h.artifact_type === "work-item").length,
+      messages: hints.map((h) => h.message).filter(Boolean)
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/core/knowledge-discovery.ts
+var KNOWLEDGE4 = "knowledge";
 var CONSOLIDATED_TYPE = {
   Business: "business",
   Product: "product",
@@ -5628,10 +6127,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(`/${KNOWLEDGE4}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE4}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE4}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE4}/delivery/`)) return "Delivery";
   return null;
 }
 function basename(p2) {
@@ -5644,7 +6143,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE2);
+  const archDir = join(dir, KNOWLEDGE4);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -5666,7 +6165,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, KNOWLEDGE4, "tech", "decisions"))) acc.Tech.structured = true;
   return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
     layer: layer2,
     status: statusFor(layer2, acc[layer2]),
@@ -5915,6 +6414,8 @@ function buildProjectExplanation(dir) {
     domains,
     duplicateWorkItems,
     externalCapsules: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
+    graphHints: loadGraphHints(dir),
     layers,
     roadmap,
     mappedModules,
@@ -6054,6 +6555,17 @@ 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.graphHints) {
+      lines.push(`- Quality: ${exp.graphHints.quality}`);
+      lines.push(`- Hints: ${exp.graphHints.totalHints}`);
+    }
+    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 +6973,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     phase,
     deliveryMix,
     external: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
+    graphHints: loadGraphHints(dir),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -6626,6 +7140,34 @@ 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");
+  }
+  if (pack.graphHints && pack.graphHints.totalHints > 0) {
+    parts.push("## Graph Hints\n");
+    parts.push(
+      [
+        `Graph relationship quality: ${pack.graphHints.quality}`,
+        `Active hints: ${pack.graphHints.activeWorkItemHints}`,
+        "Suggested agent: graph-agent"
+      ].join("\n") + "\n"
+    );
+    const shown = pack.graphHints.messages.slice(0, 3);
+    parts.push(shown.map((m) => `- ${m}`).join("\n") + "\n");
+    if (pack.graphHints.totalHints > shown.length) {
+      parts.push(`(+${pack.graphHints.totalHints - shown.length} more in \`.kaddo/graph-hints.md\`)
+`);
+    }
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -6955,6 +7497,15 @@ function runUnderstand() {
     }
     console.log("  \u2192 Review the relevant capsule before changing integration behavior with it.");
   }
+  const graphHints = loadGraphHints(dir);
+  if (assessment.phase === "Active Delivery" && graphHints && graphHints.activeWorkItemHints > 0) {
+    console.log("");
+    console.log(
+      `Graph hints: ${graphHints.activeWorkItemHints} active Work Item(s) have limited graph relationships (quality: ${graphHints.quality}).`
+    );
+    console.log("  \u2192 Review graph hints before continuing with implementation.");
+    console.log("  Suggested agent: graph-agent (see .kaddo/graph-hints.md)");
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");
@@ -8067,7 +8618,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE3 = `---
+var KNOWLEDGE5 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -9077,7 +9628,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: KNOWLEDGE5
   },
   // business / product (bootstrap — consolidated, minimal)
   {
@@ -9729,7 +10280,7 @@ async function runBootstrap(dir = cwd()) {
 }
 
 // src/commands/capsule.ts
-function slug(s) {
+function slug3(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 }
 function runCapsuleExport() {
@@ -9737,7 +10288,7 @@ function runCapsuleExport() {
   const config = requireConfig(dir);
   intro2("kaddo capsule export");
   const capsule = buildCapsule(dir, config);
-  const name = slug(config.project.name);
+  const name = slug3(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 +10324,47 @@ 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 hints = buildGraphHints(dir, graph);
+  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, "/"));
+  }
+  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.info(`Scope: ${scope} \xB7 Nodes: ${graph.nodes.length} \xB7 Edges: ${graph.edges.length}`);
+  log2.info(`Relationship quality: ${hints.quality}`);
+  if (hints.hints.length > 0) {
+    const shown = hints.hints.slice(0, 5);
+    log2.warn(`${hints.hints.length} metadata hint(s) available:`);
+    for (const h of shown) log2.info(`- ${h.message}`);
+    if (hints.hints.length > shown.length) {
+      log2.info(`\u2026and ${hints.hints.length - shown.length} more \u2014 see .kaddo/graph-hints.md`);
+    }
+  }
+  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 +10389,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.5",
+  "version": "3.18.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {