@kaddo/cli 3.17.0 → 3.19.0

package/README.md

@@ -454,7 +454,12 @@ Nodes come from knowledge layers, Work Items, code globs, capabilities, ADRs and
 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
+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
@@ -499,6 +504,7 @@ create --from roadmap → owners → guard → explain`.
 | 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

@@ -1652,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"],
@@ -3207,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 },
@@ -3230,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) }));
 
@@ -3246,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",
@@ -3391,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) => ({
@@ -4161,8 +4246,8 @@ async function runCreate(type, opts = {}) {
     answers[question.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug3 = slugify(title);
-  const fileName = `${id}-${slug3}.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);
@@ -4202,8 +4287,8 @@ async function runCreateModule(dir, modType) {
     answers[q.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug3 = slugify(title);
-  const fileName = `${id}-${slug3}.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);
@@ -4335,8 +4420,8 @@ function buildRoadmapWorkItem(opts) {
   const { id, type, level, candidate } = opts;
   const answers = opts.answers ?? {};
   const title = candidate.title.trim();
-  const slug3 = slugify(title);
-  const fileName = `${id}-${slug3}.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);
@@ -4485,7 +4570,8 @@ function parseArtifact(filePath, raw) {
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
       source: data.source ? String(data.source) : "",
       sourceId: String(data.source_id ?? ""),
-      decisions: Array.isArray(data.decisions) ? data.decisions.map(String).filter(Boolean) : []
+      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;
@@ -5697,6 +5783,11 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       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 {
@@ -5710,18 +5801,6 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
     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";
 }
@@ -5776,8 +5855,237 @@ function loadGraphSummary(dir) {
   }
 }
 
-// src/core/knowledge-discovery.ts
+// 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",
@@ -5819,10 +6127,10 @@ function layerForType(type) {
 }
 function layerFromPath(filePath) {
   const p2 = filePath.replace(/\\/g, "/");
-  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";
+  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) {
@@ -5835,7 +6143,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE3);
+  const archDir = join(dir, KNOWLEDGE4);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -5857,7 +6165,7 @@ function discoverLayers(dir) {
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE3, "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]),
@@ -6107,6 +6415,7 @@ function buildProjectExplanation(dir) {
     duplicateWorkItems,
     externalCapsules: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
+    graphHints: loadGraphHints(dir),
     layers,
     roadmap,
     mappedModules,
@@ -6250,6 +6559,10 @@ function renderExplanationHuman(exp) {
     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("");
   }
@@ -6661,6 +6974,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     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
@@ -6838,6 +7152,22 @@ function renderContextPack(pack) {
     );
     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");
@@ -7167,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("");
@@ -8279,7 +8618,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE4 = `---
+var KNOWLEDGE5 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -9289,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: KNOWLEDGE4
+    content: KNOWLEDGE5
   },
   // business / product (bootstrap — consolidated, minimal)
   {
@@ -9941,7 +10280,7 @@ async function runBootstrap(dir = cwd()) {
 }
 
 // src/commands/capsule.ts
-function slug2(s) {
+function slug3(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 }
 function runCapsuleExport() {
@@ -9949,7 +10288,7 @@ function runCapsuleExport() {
   const config = requireConfig(dir);
   intro2("kaddo capsule export");
   const capsule = buildCapsule(dir, config);
-  const name = slug2(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));
@@ -9995,6 +10334,7 @@ function runGraphExport(opts = {}) {
   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");
@@ -10006,13 +10346,20 @@ function runGraphExport(opts = {}) {
     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.");
-  }
+  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.");

package/package.json

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