@kaddo/mcp 3.22.1 → 3.23.0

package/dist/index.js

@@ -90,12 +90,13 @@ var DERIVED_WRITE_FILES = /* @__PURE__ */ new Set([
   ".kaddo/graph-hints.json"
 ]);
 var DERIVED_EXPORTS_RE = /^\.kaddo\/exports\/[^/]+\.capsule\.(md|json)$/;
+var DERIVED_REPORTS_RE = /^\.kaddo\/reports\/[^/]+\.(md|json)$/;
 function assertMcpDerivedWritePath(relPath) {
   const p = toPosix(relPath).replace(/^\/+/, "");
   if (path.isAbsolute(relPath) || p.split("/").some((seg) => seg === "..")) {
     throw new KaddoMcpError("Blocked unsafe MCP derived write path.");
   }
-  if (!DERIVED_WRITE_FILES.has(p) && !DERIVED_EXPORTS_RE.test(p)) {
+  if (!DERIVED_WRITE_FILES.has(p) && !DERIVED_EXPORTS_RE.test(p) && !DERIVED_REPORTS_RE.test(p)) {
     throw new KaddoMcpError("Blocked unsafe MCP derived write path.");
   }
   return p;
@@ -249,367 +250,51 @@ function getSkill(root, id) {
   return { ...info, content, description: firstHeadingOrLine2(content) || info.title };
 }
 
-// src/workitems.ts
-import matter3 from "gray-matter";
-var ACTIVE_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
-function strArray(v) {
-  return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
+// ../cli/src/utils/fs.ts
+import fs2 from "fs";
+import path2 from "path";
+function exists(p) {
+  return fs2.existsSync(p);
 }
-function lifecycleOf(data, relPath) {
-  const status = String(data.status ?? "").trim();
-  if (status) return status;
-  const segs = relPath.split("/");
-  const folder = segs[segs.length - 2];
-  return ACTIVE_STATES.has(folder) || folder === "completed" || folder === "archived" ? folder : "ready";
+function readFile(p) {
+  return fs2.readFileSync(p, "utf-8");
 }
-function firstParagraph(body) {
-  for (const block of body.split(/\n\s*\n/)) {
-    const t = block.trim();
-    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
-  }
-  return "";
+function readDir(dirPath) {
+  if (!exists(dirPath)) return [];
+  return fs2.readdirSync(dirPath);
 }
-function listWorkItems(root) {
-  const files = listFiles(root, "knowledge/delivery/work-items", ".md");
-  const items = [];
-  for (const rel of files) {
-    const raw = readText(root, rel);
-    if (raw === null) continue;
-    let parsed;
-    try {
-      parsed = matter3(raw);
-    } catch {
-      continue;
-    }
-    const data = parsed.data;
-    if (!data.type) continue;
-    items.push({
-      id: String(data.id ?? "") || rel,
-      title: String(data.title ?? ""),
-      status: lifecycleOf(data, rel),
-      type: String(data.type ?? ""),
-      knowledge_level: String(data.knowledge_level ?? ""),
-      path: rel,
-      summary: String(data.summary ?? "") || firstParagraph(parsed.content),
-      code: strArray(data.code),
-      capabilities: strArray(data.capabilities),
-      decisions: strArray(data.decisions),
-      capsules: strArray(data.capsules)
-    });
-  }
-  return items.sort((a, b) => a.id.localeCompare(b.id));
+function isFile(p) {
+  return exists(p) && fs2.statSync(p).isFile();
 }
-
-// src/resources.ts
-function text(uri, body, mimeType = "text/markdown") {
-  return [{ uri, text: body, mimeType }];
+function isDir(p) {
+  return exists(p) && fs2.statSync(p).isDirectory();
 }
-function fileOrHint(root, uri, rel, hint, mimeType = "text/markdown") {
-  const body = readText(root, rel);
-  return text(uri, body ?? hint, body ? mimeType : "text/plain");
+function join(...parts) {
+  return path2.join(...parts);
 }
-var RESOURCES = [
-  {
-    uri: "kaddo://context-pack",
-    name: "Kaddo context pack",
-    description: "Curated LLM context pack (.kaddo/context-pack.md).",
-    mimeType: "text/markdown",
-    read: (root) => fileOrHint(
-      root,
-      "kaddo://context-pack",
-      ".kaddo/context-pack.md",
-      "Context pack not found. Run `kaddo context` in the project first."
-    )
-  },
-  {
-    uri: "kaddo://explain",
-    name: "Kaddo explain",
-    description: "What Kaddo knows about the project (.kaddo/explain.md).",
-    mimeType: "text/markdown",
-    read: (root) => fileOrHint(
-      root,
-      "kaddo://explain",
-      ".kaddo/explain.md",
-      "Explain output not found. Run `kaddo explain` first."
-    )
-  },
-  {
-    uri: "kaddo://understand",
-    name: "Kaddo understand",
-    description: "Current phase and recommended next step (.kaddo/understand.md).",
-    mimeType: "text/markdown",
-    read: (root) => fileOrHint(
-      root,
-      "kaddo://understand",
-      ".kaddo/understand.md",
-      "Understand output not found. Run `kaddo understand` first."
-    )
-  },
-  {
-    uri: "kaddo://graph",
-    name: "Kaddo knowledge graph",
-    description: "Knowledge graph (.kaddo/graph.json + .kaddo/graph.mmd).",
-    mimeType: "application/json",
-    read: (root) => {
-      const json = readText(root, ".kaddo/graph.json");
-      const mmd = readText(root, ".kaddo/graph.mmd");
-      if (!json && !mmd) {
-        return text("kaddo://graph", "Knowledge graph not found. Run `kaddo graph export` first.", "text/plain");
-      }
-      const parts = [];
-      if (json) parts.push({ uri: "kaddo://graph", text: json, mimeType: "application/json" });
-      if (mmd) parts.push({ uri: "kaddo://graph.mmd", text: mmd, mimeType: "text/vnd.mermaid" });
-      return parts;
-    }
-  },
-  {
-    uri: "kaddo://graph-hints",
-    name: "Kaddo graph hints",
-    description: "Graph relationship-quality hints (.kaddo/graph-hints.md + .json).",
-    mimeType: "text/markdown",
-    read: (root) => {
-      const md = readText(root, ".kaddo/graph-hints.md");
-      const json = readText(root, ".kaddo/graph-hints.json");
-      if (!md && !json) {
-        return text("kaddo://graph-hints", "Graph hints not found. Run `kaddo graph export` first.", "text/plain");
-      }
-      const parts = [];
-      if (md) parts.push({ uri: "kaddo://graph-hints", text: md, mimeType: "text/markdown" });
-      if (json) parts.push({ uri: "kaddo://graph-hints.json", text: json, mimeType: "application/json" });
-      return parts;
-    }
-  },
-  {
-    uri: "kaddo://work-items",
-    name: "Kaddo work items",
-    description: "Summarized Work Items from knowledge/delivery/work-items/.",
-    mimeType: "application/json",
-    read: (root) => {
-      if (!hasKnowledge(root)) {
-        return text("kaddo://work-items", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
-      }
-      return [
-        {
-          uri: "kaddo://work-items",
-          text: JSON.stringify(listWorkItems(root), null, 2),
-          mimeType: "application/json"
-        }
-      ];
-    }
-  },
-  {
-    uri: "kaddo://roadmap",
-    name: "Kaddo roadmap",
-    description: "Delivery roadmap (knowledge/delivery/roadmap.md).",
-    mimeType: "text/markdown",
-    read: (root) => fileOrHint(
-      root,
-      "kaddo://roadmap",
-      "knowledge/delivery/roadmap.md",
-      "Roadmap not found. Create knowledge/delivery/roadmap.md (e.g. via the roadmap-agent) first."
-    )
-  },
-  {
-    uri: "kaddo://capsules",
-    name: "Kaddo knowledge capsules",
-    description: "External Knowledge Capsules from .kaddo/external.yml and external/.",
-    mimeType: "application/json",
-    read: (root) => [
-      {
-        uri: "kaddo://capsules",
-        text: JSON.stringify(listCapsules(root), null, 2),
-        mimeType: "application/json"
-      }
-    ]
-  },
-  {
-    uri: "kaddo://agents",
-    name: "Kaddo agents",
-    description: "Installed agent prompts from knowledge/agents/.",
-    mimeType: "application/json",
-    read: (root) => [
-      {
-        uri: "kaddo://agents",
-        text: JSON.stringify(listAgents(root), null, 2),
-        mimeType: "application/json"
-      }
-    ]
-  },
-  {
-    uri: "kaddo://skills",
-    name: "Kaddo skills",
-    description: "Installed reusable skills from knowledge/skills/ (empty if none).",
-    mimeType: "application/json",
-    read: (root) => [
-      {
-        uri: "kaddo://skills",
-        text: JSON.stringify({ skills: listSkills(root) }, null, 2),
-        mimeType: "application/json"
-      }
-    ]
-  }
-];
 
-// src/prompts.ts
-var EXTRA_INPUTS = {
-  "graph-agent": [".kaddo/graph.json", ".kaddo/graph-hints.md"],
-  "ownership-agent": ["knowledge/delivery/work-items/", "knowledge/inventory.md"],
-  "capsule-agent": ["knowledge/product/capabilities.md", "knowledge/tech/decisions/"],
-  "work-item-agent": ["knowledge/delivery/roadmap.md"],
-  "implementation-agent": ["knowledge/tech/git-strategy.md"]
+// ../cli/src/core/impact-report.ts
+import matter6 from "gray-matter";
+
+// ../cli/src/core/config.ts
+import { z } from "zod";
+import { parse as parseYaml2 } from "yaml";
+var PROJECT_STATES = ["new", "pre-ai", "legacy"];
+var TEAM_SIZES = ["indie", "small", "medium", "enterprise"];
+var REPOSITORY_STRUCTURES = ["monorepo", "multirepo"];
+var PROJECT_LANGUAGES = ["en", "es"];
+var DEFAULTS = {
+  state: "pre-ai",
+  structure: "monorepo",
+  teamSize: "indie",
+  language: "en"
 };
-function recommendedInputs(name) {
-  return [".kaddo/context-pack.md", ...EXTRA_INPUTS[name] ?? []];
-}
-function listPrompts(root) {
-  return listAgents(root).map((a) => ({
-    name: a.name,
-    description: a.description || `Kaddo ${a.name}`,
-    content: "",
-    recommended_inputs: recommendedInputs(a.name)
-  }));
+function languageLabel(lang) {
+  return lang === "es" ? "Spanish" : "English";
 }
-function getPrompt(root, name) {
-  const agent = getAgentPrompt(root, name);
-  if (!agent) return null;
-  return {
-    name: agent.name,
-    description: agent.description || `Kaddo ${agent.name}`,
-    content: agent.content,
-    recommended_inputs: recommendedInputs(agent.name)
-  };
-}
-
-// src/tools.ts
-var ok = (data) => ({ ok: true, data });
-var fail = (message) => ({ ok: false, message });
-function projectStatus(root) {
-  const explain = readJson(root, ".kaddo/explain.json");
-  const hints = readJson(root, ".kaddo/graph-hints.json");
-  const capsules = listCapsules(root);
-  if (!explain) {
-    return fail("Project status needs `.kaddo/explain.json`. Run `kaddo explain` first.");
-  }
-  const maturity = (explain.layers ?? []).map((l) => `${l.layer}: ${l.status}`);
-  return ok({
-    project: explain.project?.name ?? "unknown",
-    state: explain.project?.state ?? "unknown",
-    knowledgeMaturity: maturity,
-    workItems: {
-      total: explain.workItems?.total ?? 0,
-      byState: explain.workItems?.byState ?? {},
-      byType: explain.workItems?.byType ?? {}
-    },
-    ownership: {
-      withOwnership: explain.ownership?.workItemsWithOwnership ?? 0,
-      total: explain.ownership?.workItemsTotal ?? 0
-    },
-    graph: {
-      scope: hints?.scope ?? "unknown (run `kaddo graph export`)",
-      scope_reason: hints?.scope_reason ?? "",
-      quality: hints?.quality ?? "unknown (run `kaddo graph export`)",
-      hints: hints?.summary?.hints ?? 0
-    },
-    capsules: capsules.length
-  });
-}
-function listWorkItemsTool(root, filter = {}) {
-  let items = listWorkItems(root);
-  if (filter.status) items = items.filter((w) => w.status === filter.status);
-  if (filter.type) items = items.filter((w) => w.type === filter.type);
-  if (filter.knowledge_level) items = items.filter((w) => w.knowledge_level === filter.knowledge_level);
-  return ok(items);
-}
-function getWorkItem(root, id) {
-  const item = listWorkItems(root).find((w) => w.id === id);
-  if (!item) return fail(`Work Item "${id}" not found.`);
-  const content = readText(root, item.path);
-  return ok({ ...item, content: content ?? "" });
-}
-function listCapsulesTool(root) {
-  return ok(listCapsules(root));
-}
-function getCapsuleTool(root, id) {
-  const cap = getCapsule(root, id);
-  if (!cap) return fail(`Knowledge Capsule "${id}" not found.`);
-  return ok(cap);
-}
-function listAgentsTool(root) {
-  return ok(listAgents(root));
-}
-function getAgentPromptTool(root, name) {
-  const agent = getAgentPrompt(root, name);
-  if (!agent) return fail(`Agent "${name}" is not installed. Run \`kaddo add agents\` first.`);
-  return ok(agent);
-}
-function listSkillsTool(root) {
-  return ok(listSkills(root));
-}
-function getSkillTool(root, id) {
-  const skill = getSkill(root, id);
-  if (!skill) return fail(`Skill "${id}" is not installed. Run \`kaddo add skills\` first.`);
-  return ok(skill);
-}
-function listGraphHints(root, filter = {}) {
-  const report = readJson(root, ".kaddo/graph-hints.json");
-  if (!report) return fail("Graph hints not found. Run `kaddo graph export` first.");
-  let hints = Array.isArray(report.hints) ? report.hints : [];
-  if (filter.artifact_type) hints = hints.filter((h) => h.artifact_type === filter.artifact_type);
-  if (filter.severity) hints = hints.filter((h) => h.severity === filter.severity);
-  if (filter.active_only) hints = hints.filter((h) => h.artifact_type === "work-item");
-  return ok({
-    scope: report.scope ?? "active",
-    scope_reason: report.scope_reason ?? "",
-    quality: report.quality ?? "unknown",
-    count: hints.length,
-    hints
-  });
-}
-
-// ../cli/src/core/config.ts
-import { z } from "zod";
-
-// ../cli/src/utils/fs.ts
-import fs2 from "fs";
-import path2 from "path";
-function exists(p) {
-  return fs2.existsSync(p);
-}
-function readFile(p) {
-  return fs2.readFileSync(p, "utf-8");
-}
-function readDir(dirPath) {
-  if (!exists(dirPath)) return [];
-  return fs2.readdirSync(dirPath);
-}
-function isFile(p) {
-  return exists(p) && fs2.statSync(p).isFile();
-}
-function isDir(p) {
-  return exists(p) && fs2.statSync(p).isDirectory();
-}
-function join(...parts) {
-  return path2.join(...parts);
-}
-
-// ../cli/src/core/config.ts
-import { parse as parseYaml2 } from "yaml";
-var PROJECT_STATES = ["new", "pre-ai", "legacy"];
-var TEAM_SIZES = ["indie", "small", "medium", "enterprise"];
-var REPOSITORY_STRUCTURES = ["monorepo", "multirepo"];
-var PROJECT_LANGUAGES = ["en", "es"];
-var DEFAULTS = {
-  state: "pre-ai",
-  structure: "monorepo",
-  teamSize: "indie",
-  language: "en"
-};
-function languageLabel(lang) {
-  return lang === "es" ? "Spanish" : "English";
-}
-function projectLanguage(config) {
-  const lang = config.project.language;
-  return lang === "es" ? "es" : "en";
+function projectLanguage(config) {
+  const lang = config.project.language;
+  return lang === "es" ? "es" : "en";
 }
 var ConfigError = class extends Error {
   constructor(message) {
@@ -678,14 +363,11 @@ ${issues}`);
   return parsed.data;
 }
 
-// ../cli/src/core/context-pack.ts
-import matter7 from "gray-matter";
-
 // ../cli/src/services/artifact-reader.ts
-import matter4 from "gray-matter";
+import matter3 from "gray-matter";
 function parseArtifact(filePath, raw) {
   try {
-    const { data } = matter4(raw);
+    const { data } = matter3(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -737,7 +419,7 @@ var LIFECYCLE_STATES = [
   "completed",
   "archived"
 ];
-var ACTIVE_STATES2 = ["draft", "ready", "in-progress", "blocked"];
+var ACTIVE_STATES = ["draft", "ready", "in-progress", "blocked"];
 var LEGACY_STATUS_MAP = {
   done: "completed",
   cancelled: "archived",
@@ -749,7 +431,7 @@ function isLifecycleState(s) {
   return STATE_SET.has(s);
 }
 function isActiveState(s) {
-  return ACTIVE_STATES2.includes(s);
+  return ACTIVE_STATES.includes(s);
 }
 function lifecycleFolderOf(filePath) {
   const p = filePath.replace(/\\/g, "/");
@@ -816,944 +498,552 @@ function discoverWorkItems(dir) {
   return discoverKnowledge(dir).filter((a) => a.isWorkItem);
 }
 
-// ../cli/src/services/mapped-modules.ts
-import { parse as parseYaml3 } from "yaml";
-var DESCRIPTOR_PATH = ".kaddo/modules.yml";
-function toStringArray(value) {
-  return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
+// ../cli/src/core/delivery-phase.ts
+function layer(layers, name) {
+  return layers.find((l) => l.layer === name)?.status ?? "Missing";
 }
-function moduleArtifactCoverage(dir, id) {
-  const base = join(dir, "knowledge", "tech", "modules", id);
-  return {
-    moduleDesign: exists(join(base, "module-design.md")),
-    stack: exists(join(base, "stack.md")),
-    security: exists(join(base, "security.md")),
-    standards: exists(join(base, "standards.md")),
-    diagrams: exists(join(base, "diagrams")),
-    adrs: exists(join(base, "adrs"))
-  };
+function baseComplete(layers) {
+  return layer(layers, "Business") !== "Missing" && layer(layers, "Product") !== "Missing" && layer(layers, "Tech") !== "Missing";
 }
-function loadMappedModules(dir) {
-  const path3 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path3)) return [];
-  let parsed;
-  try {
-    parsed = parseYaml3(readFile(path3));
-  } catch {
-    return [];
+function determinePhase(input) {
+  const { roadmap, workItems } = input;
+  const active = workItems.byState.draft + workItems.byState.ready + workItems.byState["in-progress"] + workItems.byState.blocked;
+  if (!baseComplete(input.layers)) return "Discovery";
+  if (!roadmap.present) return "Planning";
+  if (workItems.total === 0) return "Delivery Preparation";
+  if (active > 0) return "Active Delivery";
+  return "Maintenance";
+}
+function ownershipPct(o) {
+  if (o.workItemsTotal === 0) return 100;
+  return Math.round(o.workItemsWithOwnership / o.workItemsTotal * 100);
+}
+function buildReasons(input) {
+  const reasons = [];
+  reasons.push(input.roadmap.present ? "Roadmap available" : "No roadmap yet");
+  if (input.roadmap.present) {
+    reasons.push(`${input.roadmap.materialized} materialized work item(s)`);
+    if (input.roadmap.remaining > 0) reasons.push(`${input.roadmap.remaining} roadmap candidate(s) remaining`);
   }
-  const raw = Array.isArray(parsed?.modules) ? parsed.modules : [];
-  const modules = [];
-  for (const entry of raw) {
-    if (!entry || typeof entry !== "object") continue;
-    const m = entry;
-    const id = typeof m.id === "string" ? m.id : "";
-    if (!id) continue;
-    modules.push({
-      id,
-      name: typeof m.name === "string" ? m.name : void 0,
-      repoPath: typeof m.repoPath === "string" ? m.repoPath : "",
-      type: typeof m.type === "string" ? m.type : void 0,
-      mainTechnology: typeof m.mainTechnology === "string" ? m.mainTechnology : void 0,
-      owner: typeof m.owner === "string" ? m.owner : void 0,
-      capabilities: toStringArray(m.capabilities),
-      code: toStringArray(m.code),
-      status: typeof m.status === "string" ? m.status : void 0,
-      artifacts: moduleArtifactCoverage(dir, id)
-    });
+  const active = LIFECYCLE_STATES.filter((s) => input.workItems.byState[s] > 0 && s !== "completed" && s !== "archived");
+  if (active.length > 0) {
+    reasons.push(active.map((s) => `${s}: ${input.workItems.byState[s]}`).join(", "));
   }
-  return modules;
+  if (input.workItems.total > 0) reasons.push(`Ownership coverage ${ownershipPct(input.ownership)}%`);
+  return reasons;
 }
-function presentArtifacts(coverage) {
-  const present = [];
-  if (coverage.moduleDesign) present.push("module-design");
-  if (coverage.stack) present.push("stack");
-  if (coverage.security) present.push("security");
-  if (coverage.standards) present.push("standards");
-  if (coverage.diagrams) present.push("diagrams");
-  if (coverage.adrs) present.push("adrs");
-  return present;
+function firstMissingLayerAgent(layers) {
+  if (layer(layers, "Business") === "Missing")
+    return { agent: "business-agent", step: "Use business-agent to create knowledge/business/business.md" };
+  if (layer(layers, "Product") === "Missing")
+    return { agent: "capability-agent", step: "Use capability-agent to create knowledge/product/capabilities.md" };
+  return { agent: "architecture-agent", step: "Use architecture-agent to create knowledge/tech/current-state.md" };
 }
-
-// ../cli/src/core/knowledge-discovery.ts
-var KNOWLEDGE = "knowledge";
-var CONSOLIDATED_TYPE = {
-  Business: "business",
-  Product: "product",
-  Tech: "codebase"
-};
-var STRUCTURED_TYPES = {
-  Business: /* @__PURE__ */ new Set(["problem", "users", "value-proposition", "business-rules", "constraints", "glossary"]),
-  Product: /* @__PURE__ */ new Set(["product-brief", "capabilities"]),
-  Tech: /* @__PURE__ */ new Set([
-    "current-state",
-    "architecture-notes",
-    "decision-candidates",
-    "quality-attributes",
-    "stack",
-    "standards",
-    "security",
-    "git-strategy",
-    "module-design",
-    "adr",
-    "decision"
-  ]),
-  Delivery: /* @__PURE__ */ new Set([])
-};
-var WORK_ITEM_TYPES = /* @__PURE__ */ new Set([
-  "work-item",
-  "feature",
-  "bugfix",
-  "hotfix",
-  "spike"
-]);
-function layerForType(type) {
-  if (!type) return null;
-  if (type === CONSOLIDATED_TYPE.Business || STRUCTURED_TYPES.Business.has(type)) return "Business";
-  if (type === CONSOLIDATED_TYPE.Product || STRUCTURED_TYPES.Product.has(type)) return "Product";
-  if (type === CONSOLIDATED_TYPE.Tech || STRUCTURED_TYPES.Tech.has(type) || type === "knowledge")
-    return "Tech";
-  if (type === "roadmap" || WORK_ITEM_TYPES.has(type)) return "Delivery";
-  return null;
-}
-function layerFromPath(filePath) {
-  const p = filePath.replace(/\\/g, "/");
-  if (p.includes(`/${KNOWLEDGE}/business/`)) return "Business";
-  if (p.includes(`/${KNOWLEDGE}/product/`)) return "Product";
-  if (p.includes(`/${KNOWLEDGE}/tech/`)) return "Tech";
-  if (p.includes(`/${KNOWLEDGE}/delivery/`)) return "Delivery";
-  return null;
-}
-function basename(p) {
-  return p.replace(/\\/g, "/").split("/").pop() ?? p;
-}
-function discoverLayers(dir) {
-  const acc = {
-    Business: blank(),
-    Product: blank(),
-    Tech: blank(),
-    Delivery: blank()
-  };
-  const archDir = join(dir, KNOWLEDGE);
-  const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
-  for (const a of artifacts) {
-    const type = a.type;
-    const layer2 = layerForType(type) ?? layerFromPath(a.filePath);
-    if (!layer2) continue;
-    const slot = acc[layer2];
-    slot.detected.add(basename(a.filePath));
-    if (layer2 === "Delivery") {
-      if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
-      if (WORK_ITEM_TYPES.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
-        if (a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) slot.hasWorkItem = true;
+function assessPhase(input) {
+  const phase = determinePhase(input);
+  const reasons = buildReasons(input);
+  const bs = input.workItems.byState;
+  const items = input.workItems.items;
+  const firstOf = (s) => items.find((i) => i.lifecycle === s);
+  let recommendedAgents = [];
+  let nextStep = "";
+  let llmInstructions = [];
+  switch (phase) {
+    case "Discovery": {
+      const m = firstMissingLayerAgent(input.layers);
+      recommendedAgents = [m.agent];
+      nextStep = m.step;
+      llmInstructions = [`Use the ${m.agent} to fill the missing base knowledge.`, "Do not write code."];
+      break;
+    }
+    case "Planning": {
+      recommendedAgents = ["roadmap-agent"];
+      nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
+      llmInstructions = ["Use the roadmap-agent.", "Do not write code.", "Generate roadmap candidates."];
+      break;
+    }
+    case "Delivery Preparation": {
+      recommendedAgents = ["kaddo create --from roadmap", "work-item-agent"];
+      const n = input.roadmap.remaining || input.roadmap.candidates;
+      nextStep = `Run \`kaddo create --from roadmap\`${n ? ` (${n} candidate(s))` : ""}, then refine with work-item-agent`;
+      llmInstructions = [
+        "Materialize roadmap candidates with `kaddo create --from roadmap`.",
+        "Use the work-item-agent to refine them.",
+        "Do not implement yet."
+      ];
+      break;
+    }
+    case "Active Delivery": {
+      if (bs.ready > 0) {
+        const wi = firstOf("ready");
+        recommendedAgents = ["implementation-agent"];
+        nextStep = wi ? `Start ${wi.id} \u2014 ${wi.title} (ready \u2192 in-progress)` : "Start a ready Work Item";
+        llmInstructions = [
+          "Use the implementation-agent.",
+          "Suggest a branch name only.",
+          "Do not run git commands."
+        ];
+      } else if (bs["in-progress"] > 0) {
+        const wi = firstOf("in-progress");
+        recommendedAgents = ["implementation-agent", "kaddo scan", "kaddo owners suggest", "kaddo guard"];
+        nextStep = wi ? `Continue ${wi.id} \u2014 ${wi.title}; then run kaddo scan, owners suggest, guard` : "Continue the in-progress Work Item; then scan, owners suggest, guard";
+        llmInstructions = [
+          "Continue the in-progress Work Item with the implementation-agent.",
+          "After changes, run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`.",
+          "Do not commit, push or merge without explicit human confirmation."
+        ];
+      } else if (bs.draft > 0) {
+        const wi = firstOf("draft");
+        recommendedAgents = ["work-item-agent"];
+        nextStep = wi ? `Refine ${wi.id} from draft to ready` : "Refine a draft Work Item to ready";
+        llmInstructions = [
+          "Refine draft Work Items to ready.",
+          "Use the work-item-agent.",
+          "Do not implement unless the user explicitly asks."
+        ];
+      } else if (bs.blocked > 0) {
+        const wi = firstOf("blocked");
+        recommendedAgents = ["work-item-agent"];
+        nextStep = wi ? `Resolve the blocker on ${wi.id} \u2014 ${wi.title}` : "Resolve the blockers on active work";
+        llmInstructions = [
+          "Resolve the blockers with the work-item-agent.",
+          "Do not implement blocked work."
+        ];
       }
-      continue;
+      if (input.ownership.workItemsMissingOwnership > 0) {
+        recommendedAgents.push("kaddo owners suggest");
+        llmInstructions.push("Ownership is incomplete \u2014 propose `code:` globs (run `kaddo owners suggest`).");
+      }
+      break;
     }
-    if (type === CONSOLIDATED_TYPE[layer2]) slot.consolidated = true;
-    else if (STRUCTURED_TYPES[layer2].has(type)) slot.structured = true;
-    else if (!type) {
-      slot.consolidated = true;
+    case "Maintenance": {
+      if (input.roadmap.remaining > 0) {
+        recommendedAgents = ["kaddo create --from roadmap", "work-item-agent"];
+        nextStep = `Materialize ${input.roadmap.remaining} remaining roadmap candidate(s)`;
+        llmInstructions = ["Materialize the remaining roadmap candidates.", "Do not implement yet."];
+      } else {
+        recommendedAgents = ["roadmap-agent"];
+        nextStep = "No active work \u2014 use roadmap-agent to plan the next initiative";
+        llmInstructions = ["No active work.", "Use the roadmap-agent to plan the next initiative."];
+      }
+      break;
     }
-    if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE, "tech", "decisions"))) acc.Tech.structured = true;
-  return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
-    layer: layer2,
-    status: statusFor(layer2, acc[layer2]),
-    detected: [...acc[layer2].detected].sort()
-  }));
-}
-function blank() {
-  return {
-    consolidated: false,
-    structured: false,
-    hasRoadmap: false,
-    hasWorkItem: false,
-    hasDecision: false,
-    detected: /* @__PURE__ */ new Set()
-  };
+  return { phase, reasons, recommendedAgents, nextStep, llmInstructions };
 }
-function existsDirWithMd(d) {
-  if (!exists(d)) return false;
+
+// ../cli/src/core/capsule.ts
+import matter4 from "gray-matter";
+import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
+
+// ../cli/src/services/owners.ts
+import { parse as parseYaml3 } from "yaml";
+var CONFIG_PATH = ".kaddo/config.yml";
+function loadOwners(dir) {
+  const configPath = join(dir, CONFIG_PATH);
+  if (!exists(configPath)) return {};
   try {
-    return readDir(d).some((e) => e.endsWith(".md") && isFile(join(d, e)));
+    const config = parseYaml3(readFile(configPath));
+    const raw = config.owners ?? {};
+    const result = {};
+    for (const [domain, people] of Object.entries(raw)) {
+      result[domain] = Array.isArray(people) ? people.map(String) : [String(people)];
+    }
+    return result;
   } catch {
-    return false;
-  }
-}
-function statusFor(layer2, a) {
-  if (layer2 === "Delivery") {
-    if (a.hasWorkItem) return "Traceable";
-    if (a.hasRoadmap) return "Partial";
-    return "Missing";
+    return {};
   }
-  if (a.structured) return "Structured";
-  if (a.consolidated) return "Consolidated";
-  return "Missing";
 }
 
-// ../cli/src/core/layers.ts
-function knowledgeLayers(dir) {
-  return discoverLayers(dir);
+// ../cli/src/core/capsule.ts
+var KNOWLEDGE = "knowledge";
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
 }
-function renderLayersMarkdown(layers) {
-  const lines = [];
-  for (const { layer: layer2, status, detected } of layers) {
-    lines.push(`### ${layer2} \u2014 ${status}`);
-    if (detected.length > 0) for (const d of detected) lines.push(`- \u2713 ${d}`);
-    else lines.push("- \u2717 none");
-    lines.push("");
+function firstParagraph(md) {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n/, "");
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
   }
-  return lines.join("\n").trimEnd();
+  return "";
 }
-
-// ../cli/src/core/roadmap.ts
-var INITIATIVE_RE = /^#{2,4}\s+(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/;
-var FIELD_RE = /^\*\*(.+?):\*\*\s*(.*)$/;
-var CANDIDATE_RE = /^\s*[-*]\s+(WI-[\w-]+)\s*[:\-–]\s*(.+)$/;
-var PROPERTY_RE = /^\s+[-*]\s+([\w /]+?)\s*:\s*(.+)$/;
-var BULLET_RE = /^\s*[-*]\s+(.+)$/;
-function normalizeKey(key) {
-  return key.trim().toLowerCase();
+function readIf(dir, rel) {
+  const p = join(dir, rel);
+  return exists(p) ? readFile(p) : null;
 }
-function splitInitiatives(markdown) {
-  const blocks = [];
-  let current = null;
-  for (const line of markdown.split(/\r?\n/)) {
-    const m = line.match(INITIATIVE_RE);
-    if (m) {
-      if (current) blocks.push(current);
-      current = { initiative: { id: m[1], title: m[2].trim() || void 0 }, lines: [] };
-      continue;
-    }
-    if (current) current.lines.push(line);
-  }
-  if (current) blocks.push(current);
-  return blocks;
+function headings(md) {
+  return md.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|risks|owners|out of scope)$/i.test(h));
 }
-function parseBlock(block) {
-  const meta = { relatedCapabilities: [], dependencies: [], openQuestions: [] };
-  const rawCandidates = [];
-  let listField = null;
-  let inCandidateSection = false;
-  let current = null;
-  const flush = () => {
-    if (current) {
-      current.rawMarkdown = current.rawMarkdown.trimEnd();
-      rawCandidates.push(current);
-      current = null;
-    }
+function buildCapsule(dir, config) {
+  const ownerMap = loadOwners(dir);
+  const owners = [...new Set(Object.values(ownerMap).flat())];
+  const all = discoverKnowledge(dir);
+  const purposeSrc = readIf(dir, `${KNOWLEDGE}/business/business.md`) ?? readIf(dir, `${KNOWLEDGE}/knowledge.md`) ?? "";
+  const capsMd = readIf(dir, `${KNOWLEDGE}/product/capabilities.md`);
+  const risksMd = readIf(dir, `${KNOWLEDGE}/legacy/risks.md`);
+  const adrs = all.filter((a) => a.filePath.replace(/\\/g, "/").includes("/tech/decisions/") && Boolean(a.type)).map((a) => a.title || a.id).filter(Boolean);
+  return {
+    system: config.project.name,
+    version: 1,
+    updatedAt: today(),
+    owner: owners[0] ?? "unknown",
+    sourceProject: config.project.name,
+    purpose: firstParagraph(purposeSrc),
+    responsibilities: [],
+    capabilities: capsMd ? headings(capsMd) : [],
+    contracts: [],
+    dependencies: [],
+    knownRisks: risksMd ? headings(risksMd) : [],
+    adrs,
+    owners,
+    outOfScope: [],
+    usageNotes: []
   };
-  for (const line of block.lines) {
-    const candMatch = line.match(CANDIDATE_RE);
-    if (candMatch && inCandidateSection) {
-      flush();
-      current = { id: candMatch[1], title: candMatch[2].trim(), rawMarkdown: line.trim() + "\n" };
-      listField = null;
-      continue;
-    }
-    if (current) {
-      const propMatch = line.match(PROPERTY_RE);
-      if (propMatch) {
-        current.rawMarkdown += line.trim() + "\n";
-        const key = normalizeKey(propMatch[1]);
-        const value = propMatch[2].trim();
-        if (key === "type") current.type = value;
-        else if (key === "suggested knowledge level" || key === "knowledge level")
-          current.suggestedKnowledgeLevel = value;
-        else if (key === "expected value") current.expectedValue = value;
-        else if (key === "notes") current.notes = value;
-        continue;
-      }
-      if (line.trim() === "") {
-        flush();
-        continue;
-      }
-    }
-    const fieldMatch = line.match(FIELD_RE);
-    if (fieldMatch) {
-      const key = normalizeKey(fieldMatch[1]);
-      const value = fieldMatch[2].trim();
-      listField = null;
-      inCandidateSection = false;
-      if (key === "candidate work items") {
-        inCandidateSection = true;
-      } else if (key === "impact") {
-        meta.impact = value || void 0;
-      } else if (key === "risk") {
-        meta.risk = value || void 0;
-      } else if (key === "project area / domain" || key === "domain" || key === "project area") {
-        meta.domain = value || void 0;
-      } else if (key === "related capabilities") {
-        listField = "relatedCapabilities";
-        if (value) meta.relatedCapabilities.push(value);
-      } else if (key === "dependencies") {
-        listField = "dependencies";
-        if (value) meta.dependencies.push(value);
-      } else if (key === "open questions") {
-        listField = "openQuestions";
-        if (value) meta.openQuestions.push(value);
-      }
-      continue;
-    }
-    if (listField) {
-      const bulletMatch = line.match(BULLET_RE);
-      if (bulletMatch) {
-        const item = bulletMatch[1].trim().replace(/^candidate\s*:\s*/i, "");
-        meta[listField].push(item);
-        continue;
-      }
-      if (line.trim() === "") {
-        listField = null;
-        continue;
-      }
-    }
-  }
-  flush();
-  return rawCandidates.map((c) => ({
-    ...c,
-    initiative: block.initiative.id || block.initiative.title ? { ...block.initiative } : void 0,
-    relatedCapabilities: meta.relatedCapabilities.length ? [...meta.relatedCapabilities] : void 0,
-    domain: meta.domain,
-    impact: meta.impact,
-    risk: meta.risk,
-    dependencies: meta.dependencies.length ? [...meta.dependencies] : void 0,
-    openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0
-  }));
 }
-var WI_ID_RE = /\bWI-[A-Za-z0-9-]*\d/;
-var HEADING_RE = /^#{2,4}\s+(.*)$/;
-var FLEX_BULLET_RE = /^\s*[-*]\s+(?:\[[ xX]?\]\s+)?(WI-[A-Za-z0-9-]*\d)\b[\s:.\-–)]*\s*(.*)$/;
-var SEPARATOR_CELL_RE = /^:?-{2,}:?$/;
-function splitRow(line) {
-  return line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+function section(title, items, placeholder) {
+  if (items.length === 0) return `## ${title}
+
+_${placeholder}_
+`;
+  return `## ${title}
+
+${items.map((i) => `- ${i}`).join("\n")}
+`;
 }
-function isSeparatorRow(cells) {
-  return cells.length > 0 && cells.every((c) => SEPARATOR_CELL_RE.test(c) || c === "");
+function renderCapsuleMarkdown(c) {
+  const fm = [
+    "---",
+    "type: knowledge-capsule",
+    `system: ${c.system}`,
+    `version: ${c.version}`,
+    `updated_at: ${c.updatedAt}`,
+    `owner: ${c.owner}`,
+    `source_project: ${c.sourceProject}`,
+    ...c.sourceCommit ? [`source_commit: ${c.sourceCommit}`] : [],
+    "---"
+  ].join("\n");
+  const parts = [
+    fm,
+    "",
+    `# ${c.system} \u2014 Knowledge Capsule`,
+    "",
+    `## Purpose
+
+${c.purpose || "_To be completed by the capsule-agent._"}
+`,
+    section("Responsibilities", c.responsibilities, "List what this system is responsible for."),
+    section("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
+    section("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
+    section("Dependencies", c.dependencies, "List systems this one depends on."),
+    section("Known Risks", c.knownRisks, "List integration risks consumers should know."),
+    section("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
+    section("Owners", c.owners, "Who owns this system."),
+    section("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
+    section("Usage Notes", c.usageNotes, "How consumers should integrate."),
+    "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.",
+    ""
+  ];
+  return parts.join("\n");
 }
-function initiativeFromHeading(text2) {
-  const rm = text2.match(/^(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/);
-  if (rm) return { id: rm[1], title: rm[2].trim() || void 0 };
-  return { title: text2.trim() || void 0 };
+function serializeCapsuleJson(c) {
+  return JSON.stringify({ type: "knowledge-capsule", ...c }, null, 2) + "\n";
 }
-function extractDeps(cell) {
-  if (!cell) return void 0;
-  const ids = cell.match(/WI-[A-Za-z0-9-]*\d/g);
-  return ids && ids.length ? [...new Set(ids)] : void 0;
+var EXTERNAL_PATH = ".kaddo/external.yml";
+function loadExternalRegistry(dir) {
+  const p = join(dir, EXTERNAL_PATH);
+  if (!exists(p)) return [];
+  try {
+    const parsed = parseYaml4(readFile(p));
+    return Array.isArray(parsed?.external) ? parsed.external : [];
+  } catch {
+    return [];
+  }
 }
-function parseFlexible(markdown) {
+function sectionList(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return [];
   const out = [];
-  const seen = /* @__PURE__ */ new Set();
-  let initiative;
-  let cols = null;
-  const push = (id, title, deps, raw) => {
-    if (seen.has(id)) return;
-    seen.add(id);
-    out.push({
-      id,
-      title: title.trim() || id,
-      dependencies: deps,
-      initiative: initiative?.id || initiative?.title ? { ...initiative } : void 0,
-      rawMarkdown: raw.trim()
-    });
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const m = lines[i].match(/^\s*-\s+(.+?)\s*$/);
+    if (m && !/^_.*_$/.test(m[1])) out.push(m[1].trim());
+  }
+  return out;
+}
+function sectionParagraph2(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return "";
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const t = lines[i].trim();
+    if (t && !/^_.*_$/.test(t)) return t;
+  }
+  return "";
+}
+function parseCapsule(id, path3, md) {
+  const { data } = matter4(md);
+  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
+  let ageDays = null;
+  if (updatedAt) {
+    const d = Date.parse(updatedAt);
+    if (!Number.isNaN(d)) ageDays = Math.max(0, Math.floor((Date.now() - d) / 864e5));
+  }
+  return {
+    id,
+    path: path3,
+    system: data.system ? String(data.system) : id,
+    owner: data.owner ? String(data.owner) : void 0,
+    updatedAt,
+    purpose: sectionParagraph2(md, "Purpose"),
+    capabilities: sectionList(md, "Exposed Capabilities"),
+    contracts: sectionList(md, "Public Contracts"),
+    knownRisks: sectionList(md, "Known Risks"),
+    ageDays
   };
-  for (const line of markdown.split(/\r?\n/)) {
-    const h = line.match(HEADING_RE);
-    if (h) {
-      initiative = initiativeFromHeading(h[1]);
-      cols = null;
-      continue;
-    }
-    if (line.includes("|")) {
-      const cells = splitRow(line);
-      if (isSeparatorRow(cells)) continue;
-      const lower = cells.map((c) => c.toLowerCase());
-      const idIdx = lower.findIndex((c) => c === "id" || c === "wi" || c === "work item id");
-      if (idIdx >= 0 && !WI_ID_RE.test(line)) {
-        cols = {
-          id: idIdx,
-          title: lower.findIndex((c) => /work item|title|item|name|description/.test(c)),
-          deps: lower.findIndex((c) => /depend/.test(c))
-        };
-        continue;
-      }
-      if (WI_ID_RE.test(line)) {
-        let idCell = cols && cols.id >= 0 ? cells[cols.id] : cells.find((c) => /^WI-/.test(c));
-        const idMatch = (idCell ?? line).match(/WI-[A-Za-z0-9-]*\d/);
-        if (!idMatch) continue;
-        const id = idMatch[0];
-        const title = cols && cols.title >= 0 ? cells[cols.title] ?? "" : cells.find((c) => !/^WI-/.test(c) && c) ?? "";
-        const deps = cols && cols.deps >= 0 ? extractDeps(cells[cols.deps]) : void 0;
-        push(id, title, deps, line);
-        continue;
-      }
-      continue;
-    }
-    const b = line.match(FLEX_BULLET_RE);
-    if (b) {
-      push(b[1], b[2] ?? "", void 0, line);
-      continue;
+}
+function loadExternalCapsules(dir) {
+  const out = [];
+  for (const entry of loadExternalRegistry(dir)) {
+    const full = join(dir, entry.path);
+    if (!exists(full) || !isFile(full)) continue;
+    try {
+      out.push(parseCapsule(entry.id, entry.path, readFile(full)));
+    } catch {
     }
   }
   return out;
 }
-function parseRoadmapCandidates(markdown) {
-  const strict = splitInitiatives(markdown).flatMap(parseBlock);
-  if (strict.length > 0) return strict;
-  return parseFlexible(markdown);
+
+// ../cli/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 roadmapStats(markdown, materialized) {
-  if (markdown == null) return { present: false, candidates: 0, materialized, remaining: 0 };
-  const candidates = parseRoadmapCandidates(markdown).length;
-  return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
+function toPosix3(p) {
+  return p.replace(/\\/g, "/");
 }
-
-// ../cli/src/core/delivery-phase.ts
-function layer(layers, name) {
-  return layers.find((l) => l.layer === name)?.status ?? "Missing";
-}
-function baseComplete(layers) {
-  return layer(layers, "Business") !== "Missing" && layer(layers, "Product") !== "Missing" && layer(layers, "Tech") !== "Missing";
-}
-function determinePhase(input) {
-  const { roadmap, workItems } = input;
-  const active = workItems.byState.draft + workItems.byState.ready + workItems.byState["in-progress"] + workItems.byState.blocked;
-  if (!baseComplete(input.layers)) return "Discovery";
-  if (!roadmap.present) return "Planning";
-  if (workItems.total === 0) return "Delivery Preparation";
-  if (active > 0) return "Active Delivery";
-  return "Maintenance";
+function slug(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function ownershipPct(o) {
-  if (o.workItemsTotal === 0) return 100;
-  return Math.round(o.workItemsWithOwnership / o.workItemsTotal * 100);
+function isAdr(a) {
+  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
 }
-function buildReasons(input) {
-  const reasons = [];
-  reasons.push(input.roadmap.present ? "Roadmap available" : "No roadmap yet");
-  if (input.roadmap.present) {
-    reasons.push(`${input.roadmap.materialized} materialized work item(s)`);
-    if (input.roadmap.remaining > 0) reasons.push(`${input.roadmap.remaining} roadmap candidate(s) remaining`);
+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 path3 = layer2.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path3) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path3 });
+      presentLayers.push(layer2.id);
+    }
   }
-  const active = LIFECYCLE_STATES.filter((s) => input.workItems.byState[s] > 0 && s !== "completed" && s !== "archived");
-  if (active.length > 0) {
-    reasons.push(active.map((s) => `${s}: ${input.workItems.byState[s]}`).join(", "));
+  for (let i = 0; i < presentLayers.length - 1; i++) {
+    addEdge(presentLayers[i], presentLayers[i + 1], "informs");
   }
-  if (input.workItems.total > 0) reasons.push(`Ownership coverage ${ownershipPct(input.ownership)}%`);
-  return reasons;
-}
-function firstMissingLayerAgent(layers) {
-  if (layer(layers, "Business") === "Missing")
-    return { agent: "business-agent", step: "Use business-agent to create knowledge/business/business.md" };
-  if (layer(layers, "Product") === "Missing")
-    return { agent: "capability-agent", step: "Use capability-agent to create knowledge/product/capabilities.md" };
-  return { agent: "architecture-agent", step: "Use architecture-agent to create knowledge/tech/current-state.md" };
-}
-function assessPhase(input) {
-  const phase = determinePhase(input);
-  const reasons = buildReasons(input);
-  const bs = input.workItems.byState;
-  const items = input.workItems.items;
-  const firstOf = (s) => items.find((i) => i.lifecycle === s);
-  let recommendedAgents = [];
-  let nextStep = "";
-  let llmInstructions = [];
-  switch (phase) {
-    case "Discovery": {
-      const m = firstMissingLayerAgent(input.layers);
-      recommendedAgents = [m.agent];
-      nextStep = m.step;
-      llmInstructions = [`Use the ${m.agent} to fill the missing base knowledge.`, "Do not write code."];
-      break;
+  const all = discoverKnowledge(dir);
+  const workItems = all.filter((a) => a.isWorkItem);
+  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}`;
+    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");
     }
-    case "Planning": {
-      recommendedAgents = ["roadmap-agent"];
-      nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
-      llmInstructions = ["Use the roadmap-agent.", "Do not write code.", "Generate roadmap candidates."];
-      break;
+    for (const cap of wi.capabilities) {
+      const capId = `capability:${slug(cap) || cap}`;
+      addNode({ id: capId, type: "capability", label: cap });
+      addEdge(wiNodeId, capId, "implements");
     }
-    case "Delivery Preparation": {
-      recommendedAgents = ["kaddo create --from roadmap", "work-item-agent"];
-      const n = input.roadmap.remaining || input.roadmap.candidates;
-      nextStep = `Run \`kaddo create --from roadmap\`${n ? ` (${n} candidate(s))` : ""}, then refine with work-item-agent`;
-      llmInstructions = [
-        "Materialize roadmap candidates with `kaddo create --from roadmap`.",
-        "Use the work-item-agent to refine them.",
-        "Do not implement yet."
-      ];
-      break;
+    for (const dec of wi.decisions) {
+      const adrId = `adr:${dec}`;
+      addNode({ id: adrId, type: "decision", label: dec });
+      addEdge(wiNodeId, adrId, "depends_on");
     }
-    case "Active Delivery": {
-      if (bs.ready > 0) {
-        const wi = firstOf("ready");
-        recommendedAgents = ["implementation-agent"];
-        nextStep = wi ? `Start ${wi.id} \u2014 ${wi.title} (ready \u2192 in-progress)` : "Start a ready Work Item";
-        llmInstructions = [
-          "Use the implementation-agent.",
-          "Suggest a branch name only.",
-          "Do not run git commands."
-        ];
-      } else if (bs["in-progress"] > 0) {
-        const wi = firstOf("in-progress");
-        recommendedAgents = ["implementation-agent", "kaddo scan", "kaddo owners suggest", "kaddo guard"];
-        nextStep = wi ? `Continue ${wi.id} \u2014 ${wi.title}; then run kaddo scan, owners suggest, guard` : "Continue the in-progress Work Item; then scan, owners suggest, guard";
-        llmInstructions = [
-          "Continue the in-progress Work Item with the implementation-agent.",
-          "After changes, run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`.",
-          "Do not commit, push or merge without explicit human confirmation."
-        ];
-      } else if (bs.draft > 0) {
-        const wi = firstOf("draft");
-        recommendedAgents = ["work-item-agent"];
-        nextStep = wi ? `Refine ${wi.id} from draft to ready` : "Refine a draft Work Item to ready";
-        llmInstructions = [
-          "Refine draft Work Items to ready.",
-          "Use the work-item-agent.",
-          "Do not implement unless the user explicitly asks."
-        ];
-      } else if (bs.blocked > 0) {
-        const wi = firstOf("blocked");
-        recommendedAgents = ["work-item-agent"];
-        nextStep = wi ? `Resolve the blocker on ${wi.id} \u2014 ${wi.title}` : "Resolve the blockers on active work";
-        llmInstructions = [
-          "Resolve the blockers with the work-item-agent.",
-          "Do not implement blocked work."
-        ];
-      }
-      if (input.ownership.workItemsMissingOwnership > 0) {
-        recommendedAgents.push("kaddo owners suggest");
-        llmInstructions.push("Ownership is incomplete \u2014 propose `code:` globs (run `kaddo owners suggest`).");
-      }
-      break;
+    if (wi.initiative) {
+      const initId = `initiative:${slug(wi.initiative) || wi.initiative}`;
+      addNode({ id: initId, type: "initiative", label: wi.initiative });
+      addEdge(wiNodeId, initId, "belongs_to");
     }
-    case "Maintenance": {
-      if (input.roadmap.remaining > 0) {
-        recommendedAgents = ["kaddo create --from roadmap", "work-item-agent"];
-        nextStep = `Materialize ${input.roadmap.remaining} remaining roadmap candidate(s)`;
-        llmInstructions = ["Materialize the remaining roadmap candidates.", "Do not implement yet."];
-      } else {
-        recommendedAgents = ["roadmap-agent"];
-        nextStep = "No active work \u2014 use roadmap-agent to plan the next initiative";
-        llmInstructions = ["No active work.", "Use the roadmap-agent to plan the next initiative."];
+    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");
       }
-      break;
     }
   }
-  return { phase, reasons, recommendedAgents, nextStep, llmInstructions };
-}
-
-// ../cli/src/core/capsule.ts
-import matter5 from "gray-matter";
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
-
-// ../cli/src/services/owners.ts
-import { parse as parseYaml4 } from "yaml";
-var CONFIG_PATH = ".kaddo/config.yml";
-function loadOwners(dir) {
-  const configPath = join(dir, CONFIG_PATH);
-  if (!exists(configPath)) return {};
-  try {
-    const config = parseYaml4(readFile(configPath));
-    const raw = config.owners ?? {};
-    const result = {};
-    for (const [domain, people] of Object.entries(raw)) {
-      result[domain] = Array.isArray(people) ? people.map(String) : [String(people)];
+  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 result;
-  } catch {
-    return {};
   }
+  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: {
+      name: config.project.name,
+      state: config.project.state,
+      structure: config.project.structure
+    },
+    scope,
+    scope_reason: scopeReason,
+    included_statuses: included,
+    excluded_statuses: excluded,
+    nodes: [...nodes.values()],
+    edges
+  };
 }
-
-// ../cli/src/core/capsule.ts
-var KNOWLEDGE2 = "knowledge";
-function today() {
-  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-}
-function firstParagraph2(md) {
-  const body = md.replace(/^---\n[\s\S]*?\n---\n/, "");
-  for (const block of body.split(/\n\s*\n/)) {
-    const t = block.trim();
-    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
-  }
-  return "";
-}
-function readIf(dir, rel) {
-  const p = join(dir, rel);
-  return exists(p) ? readFile(p) : null;
-}
-function headings(md) {
-  return md.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|risks|owners|out of scope)$/i.test(h));
+function serializeGraphJson(graph) {
+  return JSON.stringify(graph, null, 2) + "\n";
 }
-function buildCapsule(dir, config) {
-  const ownerMap = loadOwners(dir);
-  const owners = [...new Set(Object.values(ownerMap).flat())];
-  const all = discoverKnowledge(dir);
-  const purposeSrc = readIf(dir, `${KNOWLEDGE2}/business/business.md`) ?? readIf(dir, `${KNOWLEDGE2}/knowledge.md`) ?? "";
-  const capsMd = readIf(dir, `${KNOWLEDGE2}/product/capabilities.md`);
-  const risksMd = readIf(dir, `${KNOWLEDGE2}/legacy/risks.md`);
-  const adrs = all.filter((a) => a.filePath.replace(/\\/g, "/").includes("/tech/decisions/") && Boolean(a.type)).map((a) => a.title || a.id).filter(Boolean);
-  return {
-    system: config.project.name,
-    version: 1,
-    updatedAt: today(),
-    owner: owners[0] ?? "unknown",
-    sourceProject: config.project.name,
-    purpose: firstParagraph2(purposeSrc),
-    responsibilities: [],
-    capabilities: capsMd ? headings(capsMd) : [],
-    contracts: [],
-    dependencies: [],
-    knownRisks: risksMd ? headings(risksMd) : [],
-    adrs,
-    owners,
-    outOfScope: [],
-    usageNotes: []
+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;
   };
-}
-function section(title, items, placeholder) {
-  if (items.length === 0) return `## ${title}
-
-_${placeholder}_
-`;
-  return `## ${title}
-
-${items.map((i) => `- ${i}`).join("\n")}
-`;
-}
-function renderCapsuleMarkdown(c) {
-  const fm = [
-    "---",
-    "type: knowledge-capsule",
-    `system: ${c.system}`,
-    `version: ${c.version}`,
-    `updated_at: ${c.updatedAt}`,
-    `owner: ${c.owner}`,
-    `source_project: ${c.sourceProject}`,
-    ...c.sourceCommit ? [`source_commit: ${c.sourceCommit}`] : [],
-    "---"
-  ].join("\n");
-  const parts = [
-    fm,
-    "",
-    `# ${c.system} \u2014 Knowledge Capsule`,
-    "",
-    `## Purpose
-
-${c.purpose || "_To be completed by the capsule-agent._"}
-`,
-    section("Responsibilities", c.responsibilities, "List what this system is responsible for."),
-    section("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
-    section("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
-    section("Dependencies", c.dependencies, "List systems this one depends on."),
-    section("Known Risks", c.knownRisks, "List integration risks consumers should know."),
-    section("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
-    section("Owners", c.owners, "Who owns this system."),
-    section("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
-    section("Usage Notes", c.usageNotes, "How consumers should integrate."),
-    "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.",
-    ""
-  ];
-  return parts.join("\n");
-}
-function serializeCapsuleJson(c) {
-  return JSON.stringify({ type: "knowledge-capsule", ...c }, null, 2) + "\n";
-}
-var EXTERNAL_PATH = ".kaddo/external.yml";
-function loadExternalRegistry(dir) {
-  const p = join(dir, EXTERNAL_PATH);
-  if (!exists(p)) return [];
-  try {
-    const parsed = parseYaml5(readFile(p));
-    return Array.isArray(parsed?.external) ? parsed.external : [];
-  } catch {
-    return [];
-  }
-}
-function sectionList(md, title) {
-  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
-  const lines = md.split(/\r?\n/);
-  const start = lines.findIndex((l) => re.test(l));
-  if (start < 0) return [];
-  const out = [];
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) break;
-    const m = lines[i].match(/^\s*-\s+(.+?)\s*$/);
-    if (m && !/^_.*_$/.test(m[1])) out.push(m[1].trim());
-  }
-  return out;
-}
-function sectionParagraph2(md, title) {
-  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
-  const lines = md.split(/\r?\n/);
-  const start = lines.findIndex((l) => re.test(l));
-  if (start < 0) return "";
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) break;
-    const t = lines[i].trim();
-    if (t && !/^_.*_$/.test(t)) return t;
+  const escapeLabel = (s) => s.replace(/"/g, "'");
+  const lines = ["flowchart LR"];
+  for (const node of graph.nodes) {
+    lines.push(`  ${safe(node.id)}["${escapeLabel(node.label)}"]`);
   }
-  return "";
-}
-function parseCapsule(id, path3, md) {
-  const { data } = matter5(md);
-  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
-  let ageDays = null;
-  if (updatedAt) {
-    const d = Date.parse(updatedAt);
-    if (!Number.isNaN(d)) ageDays = Math.max(0, Math.floor((Date.now() - d) / 864e5));
+  if (graph.edges.length > 0) lines.push("");
+  for (const edge of graph.edges) {
+    lines.push(`  ${safe(edge.from)} -->|${edge.type}| ${safe(edge.to)}`);
   }
-  return {
-    id,
-    path: path3,
-    system: data.system ? String(data.system) : id,
-    owner: data.owner ? String(data.owner) : void 0,
-    updatedAt,
-    purpose: sectionParagraph2(md, "Purpose"),
-    capabilities: sectionList(md, "Exposed Capabilities"),
-    contracts: sectionList(md, "Public Contracts"),
-    knownRisks: sectionList(md, "Known Risks"),
-    ageDays
-  };
+  return lines.join("\n") + "\n";
 }
-function loadExternalCapsules(dir) {
-  const out = [];
-  for (const entry of loadExternalRegistry(dir)) {
-    const full = join(dir, entry.path);
-    if (!exists(full) || !isFile(full)) continue;
-    try {
-      out.push(parseCapsule(entry.id, entry.path, readFile(full)));
-    } catch {
-    }
+var ACTIVE_WI_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
+function loadGraphSummary(dir) {
+  const p = join(dir, ".kaddo", "graph.json");
+  if (!exists(p)) return null;
+  try {
+    const graph = JSON.parse(readFile(p));
+    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)
+    );
+    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
+    };
+  } catch {
+    return null;
   }
-  return out;
 }
 
-// ../cli/src/core/graph.ts
+// ../cli/src/core/graph-hints.ts
 var KNOWLEDGE3 = "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 toPosix3(p) {
+function toPosix4(p) {
   return p.replace(/\\/g, "/");
 }
-function slug(s) {
+function slug2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function isAdr(a) {
-  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+function isAdr2(a) {
+  return toPosix4(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 path3 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path3) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path3 });
-      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 { 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}`;
-    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");
-        }
-      }
-    }
-  }
-  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: {
-      name: config.project.name,
-      state: config.project.state,
-      structure: config.project.structure
-    },
-    scope,
-    scope_reason: scopeReason,
-    included_statuses: included,
-    excluded_statuses: excluded,
-    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 p = join(dir, ".kaddo", "graph.json");
-  if (!exists(p)) return null;
-  try {
-    const graph = JSON.parse(readFile(p));
-    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)
-    );
-    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
-    };
-  } catch {
-    return null;
-  }
-}
-
-// ../cli/src/core/graph-hints.ts
-var KNOWLEDGE4 = "knowledge";
-function toPosix4(p) {
-  return p.replace(/\\/g, "/");
-}
-function slug2(s) {
-  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function isAdr2(a) {
-  return toPosix4(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
-}
-function capabilityHeadings(dir) {
-  const p = join(dir, KNOWLEDGE4, "product", "capabilities.md");
-  if (!exists(p)) return [];
-  return readFile(p).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 capabilityHeadings(dir) {
+  const p = join(dir, KNOWLEDGE3, "product", "capabilities.md");
+  if (!exists(p)) return [];
+  return readFile(p).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()) {
@@ -1970,7 +1260,7 @@ function loadGraphHints(dir) {
 }
 
 // ../cli/src/services/installed-skills.ts
-import matter6 from "gray-matter";
+import matter5 from "gray-matter";
 var SKILLS_DIR = join("knowledge", "skills");
 function discoverInstalledSkills(dir) {
   const base = join(dir, SKILLS_DIR);
@@ -1980,7 +1270,7 @@ function discoverInstalledSkills(dir) {
     const skillFile = join(base, entry, "skill.md");
     if (!isFile(skillFile)) continue;
     try {
-      const { data } = matter6(readFile(skillFile));
+      const { data } = matter5(readFile(skillFile));
       if (data.type && String(data.type) !== "skill") continue;
       const id = String(data.id ?? entry);
       out.push({
@@ -2001,815 +1291,1829 @@ function skillGroupCounts(skills) {
   return counts;
 }
 
-// ../cli/src/core/context-pack.ts
-var CONTEXT_PACK_VERSION = "1";
-var ARCH_DIR2 = "knowledge";
-function readScanJson(dir) {
-  const scanPath = join(dir, ".kaddo", "scan.json");
-  if (!exists(scanPath)) return null;
-  try {
-    return JSON.parse(readFile(scanPath));
-  } catch {
-    return null;
-  }
+// ../cli/src/services/mapped-modules.ts
+import { parse as parseYaml5 } from "yaml";
+var DESCRIPTOR_PATH = ".kaddo/modules.yml";
+function toStringArray(value) {
+  return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
 }
-function firstParagraph3(markdown) {
-  const body = matter7(markdown).content.trim();
-  const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
-  return para ?? "";
+function moduleArtifactCoverage(dir, id) {
+  const base = join(dir, "knowledge", "tech", "modules", id);
+  return {
+    moduleDesign: exists(join(base, "module-design.md")),
+    stack: exists(join(base, "stack.md")),
+    security: exists(join(base, "security.md")),
+    standards: exists(join(base, "standards.md")),
+    diagrams: exists(join(base, "diagrams")),
+    adrs: exists(join(base, "adrs"))
+  };
 }
-function readMarkdownSummary(dir, file) {
-  const p = join(dir, ARCH_DIR2, file);
-  if (!exists(p)) return null;
+function loadMappedModules(dir) {
+  const path3 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path3)) return [];
+  let parsed;
   try {
-    return firstParagraph3(readFile(p));
+    parsed = parseYaml5(readFile(path3));
   } catch {
-    return null;
+    return [];
   }
-}
-function recommendedAgentsForState(state) {
-  switch (state) {
-    case "new":
-      return ["roadmap-agent", "architecture-agent"];
-    case "legacy":
-      return ["legacy-agent", "architecture-agent", "capability-agent"];
-    case "pre-ai":
-    default:
-      return ["capability-agent", "architecture-agent", "roadmap-agent"];
+  const raw = Array.isArray(parsed?.modules) ? parsed.modules : [];
+  const modules = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object") continue;
+    const m = entry;
+    const id = typeof m.id === "string" ? m.id : "";
+    if (!id) continue;
+    modules.push({
+      id,
+      name: typeof m.name === "string" ? m.name : void 0,
+      repoPath: typeof m.repoPath === "string" ? m.repoPath : "",
+      type: typeof m.type === "string" ? m.type : void 0,
+      mainTechnology: typeof m.mainTechnology === "string" ? m.mainTechnology : void 0,
+      owner: typeof m.owner === "string" ? m.owner : void 0,
+      capabilities: toStringArray(m.capabilities),
+      code: toStringArray(m.code),
+      status: typeof m.status === "string" ? m.status : void 0,
+      artifacts: moduleArtifactCoverage(dir, id)
+    });
   }
+  return modules;
 }
-function nextStepsForState(state) {
-  switch (state) {
-    case "new":
-      return [
-        "Use roadmap-agent to shape an initial roadmap.",
-        "Use architecture-agent to outline the intended architecture."
-      ];
-    case "legacy":
-      return [
-        "Use legacy-agent to surface risks and unknowns before changing code.",
-        "Use architecture-agent to reconstruct the current architecture.",
-        "Use capability-agent to map existing capabilities."
-      ];
-    case "pre-ai":
-    default:
-      return [
-        "Use capability-agent to extract system capabilities.",
-        "Use architecture-agent to reconstruct the current architecture.",
-        "Use roadmap-agent to propose roadmap candidates."
-      ];
-  }
+function presentArtifacts(coverage) {
+  const present = [];
+  if (coverage.moduleDesign) present.push("module-design");
+  if (coverage.stack) present.push("stack");
+  if (coverage.security) present.push("security");
+  if (coverage.standards) present.push("standards");
+  if (coverage.diagrams) present.push("diagrams");
+  if (coverage.adrs) present.push("adrs");
+  return present;
 }
-var LLM_INSTRUCTIONS = [
-  "Use this context pack as the project baseline.",
-  "Do not write code yet.",
-  "First extract: system capabilities, architecture notes, risks, open questions and roadmap candidates.",
-  "This pack is deterministic CLI output \u2014 it does not interpret the system. That is your job."
-];
-var OPERATING_RULES = [
-  "**Never run `git commit`, `git push` or `git merge` without explicit human confirmation.**",
-  "Never push or merge automatically \u2014 ever. Suggest a Conventional Commit message and wait.",
-  "When implementing a Work Item, create a branch FIRST (per the project Git strategy, `.kaddo/git.yml`, default `feature/<id>-<slug>`). Never work directly on `main`.",
-  "After significant changes run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`, and update the affected knowledge (ADR / capabilities / current-state).",
-  "Kaddo itself never calls an LLM and never runs git \u2014 every git action is the human\u2019s."
-];
-function toContextWorkItem(a) {
-  return {
-    id: a.id,
-    type: a.type,
-    title: a.title,
-    status: a.status,
-    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
-    knowledgeLevel: a.knowledgeLevel,
-    domains: a.domains
-  };
+
+// ../cli/src/core/knowledge-discovery.ts
+var KNOWLEDGE4 = "knowledge";
+var CONSOLIDATED_TYPE = {
+  Business: "business",
+  Product: "product",
+  Tech: "codebase"
+};
+var STRUCTURED_TYPES = {
+  Business: /* @__PURE__ */ new Set(["problem", "users", "value-proposition", "business-rules", "constraints", "glossary"]),
+  Product: /* @__PURE__ */ new Set(["product-brief", "capabilities"]),
+  Tech: /* @__PURE__ */ new Set([
+    "current-state",
+    "architecture-notes",
+    "decision-candidates",
+    "quality-attributes",
+    "stack",
+    "standards",
+    "security",
+    "git-strategy",
+    "module-design",
+    "adr",
+    "decision"
+  ]),
+  Delivery: /* @__PURE__ */ new Set([])
+};
+var WORK_ITEM_TYPES = /* @__PURE__ */ new Set([
+  "work-item",
+  "feature",
+  "bugfix",
+  "hotfix",
+  "spike"
+]);
+function layerForType(type) {
+  if (!type) return null;
+  if (type === CONSOLIDATED_TYPE.Business || STRUCTURED_TYPES.Business.has(type)) return "Business";
+  if (type === CONSOLIDATED_TYPE.Product || STRUCTURED_TYPES.Product.has(type)) return "Product";
+  if (type === CONSOLIDATED_TYPE.Tech || STRUCTURED_TYPES.Tech.has(type) || type === "knowledge")
+    return "Tech";
+  if (type === "roadmap" || WORK_ITEM_TYPES.has(type)) return "Delivery";
+  return null;
 }
-function toContextArtifact(a) {
-  return { id: a.id, type: a.type, title: a.title, summary: a.summary, codeGlobs: a.codeGlobs };
+function layerFromPath(filePath) {
+  const p = filePath.replace(/\\/g, "/");
+  if (p.includes(`/${KNOWLEDGE4}/business/`)) return "Business";
+  if (p.includes(`/${KNOWLEDGE4}/product/`)) return "Product";
+  if (p.includes(`/${KNOWLEDGE4}/tech/`)) return "Tech";
+  if (p.includes(`/${KNOWLEDGE4}/delivery/`)) return "Delivery";
+  return null;
 }
-function isDeliveryWorkItem(a) {
-  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
+function basename(p) {
+  return p.replace(/\\/g, "/").split("/").pop() ?? p;
 }
-function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
-  const missing = [];
-  const scanJson = readScanJson(dir);
-  if (!scanJson) {
-    missing.push("Scan baseline missing. Run `kaddo scan` for better context.");
-  }
-  const detected = scanJson?.detected ?? {};
-  const inventoryAvailable = exists(join(dir, ARCH_DIR2, "inventory.md"));
-  if (!inventoryAvailable) {
-    missing.push("No technical inventory found. Run `kaddo scan` to generate it.");
-  }
-  const knowledgeSummary = readMarkdownSummary(dir, "knowledge.md") ?? "";
-  if (!knowledgeSummary) {
-    missing.push("No project knowledge summary found yet.");
-  }
-  const roadmapSummary = readMarkdownSummary(dir, "delivery/roadmap.md") ?? "";
-  if (!roadmapSummary) {
-    missing.push("No roadmap baseline found.");
-  }
-  const allArtifacts = discoverKnowledge(dir);
-  const workItems = allArtifacts.filter(
-    (a) => isDeliveryWorkItem(a) && isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))
-  );
-  if (workItems.length === 0) {
-    missing.push("No work items found.");
-  }
-  const state = config.project.state;
-  const roadmapPath = join(dir, ARCH_DIR2, "delivery", "roadmap.md");
-  const materialized = allArtifacts.filter(
-    (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
-  ).length;
-  const roadmap = roadmapStats(exists(roadmapPath) ? readFile(roadmapPath) : null, materialized);
-  const deliveryMix = {};
-  for (const a of allArtifacts) {
-    const p = a.filePath.replace(/\\/g, "/");
-    if (!a.type || !p.includes("/delivery/work-items/")) continue;
-    if (!isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))) continue;
-    deliveryMix[a.type] = (deliveryMix[a.type] ?? 0) + 1;
-  }
-  const mappedModules = loadMappedModules(dir);
-  const layers = knowledgeLayers(dir);
-  const allWorkItems = allArtifacts.filter((a) => a.isWorkItem);
-  const wiWithOwnership = allWorkItems.filter((a) => a.codeGlobs.length > 0).length;
-  const phase = assessPhase({
-    layers,
-    roadmap,
-    workItems: {
-      total: allWorkItems.length,
-      byState: lifecycleCounts(
-        allWorkItems.map((a) => lifecycleStateOf({ status: a.status, filePath: a.filePath }))
-      ),
-      items: allWorkItems.map((a) => ({
-        id: a.id || a.title,
-        title: a.title,
-        lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath })
-      }))
-    },
-    ownership: {
-      workItemsTotal: allWorkItems.length,
-      workItemsWithOwnership: wiWithOwnership,
-      workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
+function discoverLayers(dir) {
+  const acc = {
+    Business: blank(),
+    Product: blank(),
+    Tech: blank(),
+    Delivery: blank()
+  };
+  const archDir = join(dir, KNOWLEDGE4);
+  const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
+  for (const a of artifacts) {
+    const type = a.type;
+    const layer2 = layerForType(type) ?? layerFromPath(a.filePath);
+    if (!layer2) continue;
+    const slot = acc[layer2];
+    slot.detected.add(basename(a.filePath));
+    if (layer2 === "Delivery") {
+      if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
+      if (WORK_ITEM_TYPES.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
+        if (a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) slot.hasWorkItem = true;
+      }
+      continue;
     }
-  });
-  return {
-    version: CONTEXT_PACK_VERSION,
-    generatedAt: now.toISOString(),
-    project: {
-      name: config.project.name,
-      state,
-      teamSize: config.team.size,
-      structure: config.project.structure,
-      language: languageLabel(projectLanguage(config))
-    },
-    scan: {
-      available: scanJson !== null,
-      languages: detected.languages ?? [],
-      frameworks: detected.frameworks ?? [],
-      packageManagers: detected.packageManagers ?? [],
-      sourceDirectories: detected.sourceDirectories ?? [],
-      migrationDirectories: detected.migrationDirectories ?? [],
-      contractFiles: detected.contractFiles ?? [],
-      infrastructureFiles: detected.infrastructureFiles ?? []
-    },
-    knowledge: {
-      summary: knowledgeSummary,
-      roadmapSummary,
-      inventoryAvailable,
-      workItems: workItems.map(toContextWorkItem),
-      artifacts: allArtifacts.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
-    },
-    layers,
-    roadmap,
-    phase,
-    deliveryMix,
-    external: loadExternalCapsules(dir),
-    graph: loadGraphSummary(dir),
-    graphHints: loadGraphHints(dir),
-    skills: discoverInstalledSkills(dir).map((s) => s.id),
-    mappedModules,
-    missing,
-    // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
-    // contradicts the Current Phase block above it.
-    handoff: {
-      recommendedAgents: phase.recommendedAgents.length > 0 ? phase.recommendedAgents : recommendedAgentsForState(state),
-      nextSteps: phase.nextStep ? [phase.nextStep] : nextStepsForState(state),
-      instructions: phase.llmInstructions.length > 0 ? phase.llmInstructions : LLM_INSTRUCTIONS,
-      operatingRules: OPERATING_RULES
+    if (type === CONSOLIDATED_TYPE[layer2]) slot.consolidated = true;
+    else if (STRUCTURED_TYPES[layer2].has(type)) slot.structured = true;
+    else if (!type) {
+      slot.consolidated = true;
     }
+    if (type === "adr" || type === "decision") slot.hasDecision = 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]),
+    detected: [...acc[layer2].detected].sort()
+  }));
+}
+function blank() {
+  return {
+    consolidated: false,
+    structured: false,
+    hasRoadmap: false,
+    hasWorkItem: false,
+    hasDecision: false,
+    detected: /* @__PURE__ */ new Set()
   };
 }
-function serializeContextPackJson(pack) {
-  return JSON.stringify(pack, null, 2) + "\n";
+function existsDirWithMd(d) {
+  if (!exists(d)) return false;
+  try {
+    return readDir(d).some((e) => e.endsWith(".md") && isFile(join(d, e)));
+  } catch {
+    return false;
+  }
 }
-
-// ../cli/src/templates/context-pack-template.ts
-function renderContextPack(pack) {
-  const { project, scan, knowledge, missing, handoff } = pack;
-  const parts = [];
-  parts.push("# Kaddo Context Pack\n");
-  parts.push(
-    "> Generated by `kaddo context`. Deterministic CLI output \u2014 not an interpretation of the system.\n"
-  );
-  parts.push("## Operating Rules (read first)\n");
-  parts.push(handoff.operatingRules.map((r) => `- ${r}`).join("\n") + "\n");
-  parts.push("## Project Metadata\n");
-  parts.push(
-    [
-      `- Name: ${project.name}`,
-      `- State: ${project.state}`,
-      `- Team size: ${project.teamSize}`,
-      `- Structure: ${project.structure}`,
-      `- Language: ${project.language}`
-    ].join("\n") + "\n"
-  );
-  parts.push("## Current Phase\n");
-  parts.push(`Phase: ${pack.phase.phase}
-`);
-  if (pack.phase.reasons.length > 0) {
-    parts.push("Reason:\n");
-    parts.push(pack.phase.reasons.map((r) => `- ${r}`).join("\n") + "\n");
+function statusFor(layer2, a) {
+  if (layer2 === "Delivery") {
+    if (a.hasWorkItem) return "Traceable";
+    if (a.hasRoadmap) return "Partial";
+    return "Missing";
   }
-  if (pack.phase.recommendedAgents.length > 0) {
-    parts.push(`Recommended next: ${pack.phase.recommendedAgents.join(", ")}
-`);
+  if (a.structured) return "Structured";
+  if (a.consolidated) return "Consolidated";
+  return "Missing";
+}
+
+// ../cli/src/core/layers.ts
+function knowledgeLayers(dir) {
+  return discoverLayers(dir);
+}
+function renderLayersMarkdown(layers) {
+  const lines = [];
+  for (const { layer: layer2, status, detected } of layers) {
+    lines.push(`### ${layer2} \u2014 ${status}`);
+    if (detected.length > 0) for (const d of detected) lines.push(`- \u2713 ${d}`);
+    else lines.push("- \u2717 none");
+    lines.push("");
   }
-  if (pack.phase.nextStep) {
-    parts.push(`Next step: ${pack.phase.nextStep}
-`);
+  return lines.join("\n").trimEnd();
+}
+
+// ../cli/src/core/roadmap.ts
+var INITIATIVE_RE = /^#{2,4}\s+(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/;
+var FIELD_RE = /^\*\*(.+?):\*\*\s*(.*)$/;
+var CANDIDATE_RE = /^\s*[-*]\s+(WI-[\w-]+)\s*[:\-–]\s*(.+)$/;
+var PROPERTY_RE = /^\s+[-*]\s+([\w /]+?)\s*:\s*(.+)$/;
+var BULLET_RE = /^\s*[-*]\s+(.+)$/;
+function normalizeKey(key) {
+  return key.trim().toLowerCase();
+}
+function splitInitiatives(markdown) {
+  const blocks = [];
+  let current = null;
+  for (const line of markdown.split(/\r?\n/)) {
+    const m = line.match(INITIATIVE_RE);
+    if (m) {
+      if (current) blocks.push(current);
+      current = { initiative: { id: m[1], title: m[2].trim() || void 0 }, lines: [] };
+      continue;
+    }
+    if (current) current.lines.push(line);
   }
-  parts.push("## Knowledge Layers\n");
-  parts.push(
-    "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
-  );
-  const maturity = pack.layers.map((l) => `${l.layer}: ${l.status}`).join(" \xB7 ");
-  parts.push(`Knowledge maturity \u2014 ${maturity}
-`);
-  parts.push(renderLayersMarkdown(pack.layers) + "\n");
-  parts.push("## Technical Inventory\n");
-  if (scan.available) {
-    const lines = [
-      `- Language: ${scan.languages.join(", ") || "unknown"}`,
-      `- Framework: ${scan.frameworks.join(", ") || "unknown"}`,
-      `- Package manager: ${scan.packageManagers.join(", ") || "unknown"}`
-    ];
-    if (scan.sourceDirectories.length > 0) {
-      lines.push("- Source directories:");
-      scan.sourceDirectories.forEach((d) => lines.push(`  - ${d}`));
+  if (current) blocks.push(current);
+  return blocks;
+}
+function parseBlock(block) {
+  const meta = { relatedCapabilities: [], dependencies: [], openQuestions: [] };
+  const rawCandidates = [];
+  let listField = null;
+  let inCandidateSection = false;
+  let current = null;
+  const flush = () => {
+    if (current) {
+      current.rawMarkdown = current.rawMarkdown.trimEnd();
+      rawCandidates.push(current);
+      current = null;
     }
-    if (scan.migrationDirectories.length > 0) {
-      lines.push("- Migration directories:");
-      scan.migrationDirectories.forEach((d) => lines.push(`  - ${d}`));
+  };
+  for (const line of block.lines) {
+    const candMatch = line.match(CANDIDATE_RE);
+    if (candMatch && inCandidateSection) {
+      flush();
+      current = { id: candMatch[1], title: candMatch[2].trim(), rawMarkdown: line.trim() + "\n" };
+      listField = null;
+      continue;
     }
-    if (scan.contractFiles.length > 0) {
-      lines.push("- Contracts:");
-      scan.contractFiles.forEach((f) => lines.push(`  - ${f}`));
+    if (current) {
+      const propMatch = line.match(PROPERTY_RE);
+      if (propMatch) {
+        current.rawMarkdown += line.trim() + "\n";
+        const key = normalizeKey(propMatch[1]);
+        const value = propMatch[2].trim();
+        if (key === "type") current.type = value;
+        else if (key === "suggested knowledge level" || key === "knowledge level")
+          current.suggestedKnowledgeLevel = value;
+        else if (key === "expected value") current.expectedValue = value;
+        else if (key === "notes") current.notes = value;
+        continue;
+      }
+      if (line.trim() === "") {
+        flush();
+        continue;
+      }
     }
-    if (scan.infrastructureFiles.length > 0) {
-      lines.push("- Infrastructure:");
-      scan.infrastructureFiles.forEach((f) => lines.push(`  - ${f}`));
+    const fieldMatch = line.match(FIELD_RE);
+    if (fieldMatch) {
+      const key = normalizeKey(fieldMatch[1]);
+      const value = fieldMatch[2].trim();
+      listField = null;
+      inCandidateSection = false;
+      if (key === "candidate work items") {
+        inCandidateSection = true;
+      } else if (key === "impact") {
+        meta.impact = value || void 0;
+      } else if (key === "risk") {
+        meta.risk = value || void 0;
+      } else if (key === "project area / domain" || key === "domain" || key === "project area") {
+        meta.domain = value || void 0;
+      } else if (key === "related capabilities") {
+        listField = "relatedCapabilities";
+        if (value) meta.relatedCapabilities.push(value);
+      } else if (key === "dependencies") {
+        listField = "dependencies";
+        if (value) meta.dependencies.push(value);
+      } else if (key === "open questions") {
+        listField = "openQuestions";
+        if (value) meta.openQuestions.push(value);
+      }
+      continue;
     }
-    parts.push(lines.join("\n") + "\n");
-  } else {
-    parts.push("Scan baseline missing. Run `kaddo scan` for better context.\n");
-  }
-  parts.push("## Current Knowledge\n");
-  parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
-  parts.push("## Roadmap\n");
-  if (pack.roadmap.present) {
-    parts.push(
-      [
-        `- Roadmap candidates: ${pack.roadmap.candidates}`,
-        `- Materialized work items: ${pack.roadmap.materialized}`,
-        `- Remaining candidates: ${pack.roadmap.remaining}`
-      ].join("\n") + "\n"
-    );
-    if (pack.roadmap.remaining > 0) {
-      parts.push(
-        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
-      );
+    if (listField) {
+      const bulletMatch = line.match(BULLET_RE);
+      if (bulletMatch) {
+        const item = bulletMatch[1].trim().replace(/^candidate\s*:\s*/i, "");
+        meta[listField].push(item);
+        continue;
+      }
+      if (line.trim() === "") {
+        listField = null;
+        continue;
+      }
     }
   }
-  parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
-  parts.push("## Active Work Items\n");
-  if (knowledge.workItems.length > 0) {
-    const lines = knowledge.workItems.map((wi) => {
-      const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
-      const status = wi.lifecycle ? ` (${wi.lifecycle})` : wi.status ? ` (${wi.status})` : "";
-      const domains = wi.domains.length > 0 ? ` \xB7 domains: ${wi.domains.join(", ")}` : "";
-      return `- ${wi.id || wi.title} [${wi.type}]${level}${status} \u2014 ${wi.title}${domains}`;
+  flush();
+  return rawCandidates.map((c) => ({
+    ...c,
+    initiative: block.initiative.id || block.initiative.title ? { ...block.initiative } : void 0,
+    relatedCapabilities: meta.relatedCapabilities.length ? [...meta.relatedCapabilities] : void 0,
+    domain: meta.domain,
+    impact: meta.impact,
+    risk: meta.risk,
+    dependencies: meta.dependencies.length ? [...meta.dependencies] : void 0,
+    openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0
+  }));
+}
+var WI_ID_RE = /\bWI-[A-Za-z0-9-]*\d/;
+var HEADING_RE = /^#{2,4}\s+(.*)$/;
+var FLEX_BULLET_RE = /^\s*[-*]\s+(?:\[[ xX]?\]\s+)?(WI-[A-Za-z0-9-]*\d)\b[\s:.\-–)]*\s*(.*)$/;
+var SEPARATOR_CELL_RE = /^:?-{2,}:?$/;
+function splitRow(line) {
+  return line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+}
+function isSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((c) => SEPARATOR_CELL_RE.test(c) || c === "");
+}
+function initiativeFromHeading(text2) {
+  const rm = text2.match(/^(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/);
+  if (rm) return { id: rm[1], title: rm[2].trim() || void 0 };
+  return { title: text2.trim() || void 0 };
+}
+function extractDeps(cell) {
+  if (!cell) return void 0;
+  const ids = cell.match(/WI-[A-Za-z0-9-]*\d/g);
+  return ids && ids.length ? [...new Set(ids)] : void 0;
+}
+function parseFlexible(markdown) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let initiative;
+  let cols = null;
+  const push = (id, title, deps, raw) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push({
+      id,
+      title: title.trim() || id,
+      dependencies: deps,
+      initiative: initiative?.id || initiative?.title ? { ...initiative } : void 0,
+      rawMarkdown: raw.trim()
     });
-    parts.push(lines.join("\n") + "\n");
-  } else {
-    parts.push("No active work items found.\n");
-  }
-  const mixEntries = Object.entries(pack.deliveryMix).sort((a, b) => b[1] - a[1]);
-  if (mixEntries.length > 0) {
-    parts.push("## Delivery Mix\n");
-    parts.push("Active Work Items by type:\n");
-    const label = (t) => {
-      const c = t.charAt(0).toUpperCase() + t.slice(1);
-      return c.endsWith("s") ? c : `${c}s`;
-    };
-    parts.push(mixEntries.map(([t, n]) => `- ${label(t)}: ${n}`).join("\n") + "\n");
+  };
+  for (const line of markdown.split(/\r?\n/)) {
+    const h = line.match(HEADING_RE);
+    if (h) {
+      initiative = initiativeFromHeading(h[1]);
+      cols = null;
+      continue;
+    }
+    if (line.includes("|")) {
+      const cells = splitRow(line);
+      if (isSeparatorRow(cells)) continue;
+      const lower = cells.map((c) => c.toLowerCase());
+      const idIdx = lower.findIndex((c) => c === "id" || c === "wi" || c === "work item id");
+      if (idIdx >= 0 && !WI_ID_RE.test(line)) {
+        cols = {
+          id: idIdx,
+          title: lower.findIndex((c) => /work item|title|item|name|description/.test(c)),
+          deps: lower.findIndex((c) => /depend/.test(c))
+        };
+        continue;
+      }
+      if (WI_ID_RE.test(line)) {
+        let idCell = cols && cols.id >= 0 ? cells[cols.id] : cells.find((c) => /^WI-/.test(c));
+        const idMatch = (idCell ?? line).match(/WI-[A-Za-z0-9-]*\d/);
+        if (!idMatch) continue;
+        const id = idMatch[0];
+        const title = cols && cols.title >= 0 ? cells[cols.title] ?? "" : cells.find((c) => !/^WI-/.test(c) && c) ?? "";
+        const deps = cols && cols.deps >= 0 ? extractDeps(cells[cols.deps]) : void 0;
+        push(id, title, deps, line);
+        continue;
+      }
+      continue;
+    }
+    const b = line.match(FLEX_BULLET_RE);
+    if (b) {
+      push(b[1], b[2] ?? "", void 0, line);
+      continue;
+    }
   }
-  parts.push("## Artifacts and Ownership\n");
-  if (knowledge.artifacts.length > 0) {
-    const lines = knowledge.artifacts.map(
-      (a) => `- ${a.id || a.title} [${a.type}] owns: ${a.codeGlobs.join(", ")}`
-    );
-    parts.push(lines.join("\n") + "\n");
-  } else {
-    parts.push("No artifacts declare code ownership yet.\n");
+  return out;
+}
+function parseRoadmapCandidates(markdown) {
+  const strict = splitInitiatives(markdown).flatMap(parseBlock);
+  if (strict.length > 0) return strict;
+  return parseFlexible(markdown);
+}
+function roadmapStats(markdown, materialized) {
+  if (markdown == null) return { present: false, candidates: 0, materialized, remaining: 0 };
+  const candidates = parseRoadmapCandidates(markdown).length;
+  return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
+}
+
+// ../cli/src/core/project-explain.ts
+var ARCH_DIR2 = "knowledge";
+function normalizeTitle(t) {
+  return t.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+}
+function findDuplicateWorkItems(items) {
+  const groups = [];
+  const seen = /* @__PURE__ */ new Set();
+  const bucket = (key, reason, pred) => {
+    const matched = items.filter(pred);
+    if (matched.length > 1) {
+      const id = `${reason}:${key}:${matched.map((m) => m.id).sort().join(",")}`;
+      if (!seen.has(id)) {
+        seen.add(id);
+        groups.push({ reason, items: matched.map((m) => ({ id: m.id, title: m.title })) });
+      }
+    }
+  };
+  for (const sid of new Set(items.map((i) => i.sourceId).filter(Boolean))) {
+    bucket(sid, `same source candidate (${sid})`, (i) => i.sourceId === sid);
   }
-  if (pack.mappedModules.length > 0) {
-    parts.push("## Mapped Modules\n");
-    parts.push("This project has mapped modules registered in `.kaddo/modules.yml`.\n");
-    const header = "| Module | Type | Repo path | Owner | Capabilities | Artifacts |";
-    const sep = "|---|---|---|---|---|---|";
-    const rows = pack.mappedModules.map((m) => {
-      const caps = m.capabilities.length > 0 ? m.capabilities.join(", ") : "\u2014";
-      const arts = presentArtifacts(m.artifacts);
-      return `| ${m.id} | ${m.type ?? "\u2014"} | ${m.repoPath || "\u2014"} | ${m.owner ?? "\u2014"} | ${caps} | ${arts.length > 0 ? arts.join(", ") : "none"} |`;
-    });
-    parts.push([header, sep, ...rows].join("\n") + "\n");
-    parts.push(
-      "Note: Kaddo does not scan secondary repositories during `context`. Mapped modules come from `.kaddo/modules.yml` and module artifacts only.\n"
-    );
+  for (const nt of new Set(items.map((i) => normalizeTitle(i.title)).filter(Boolean))) {
+    bucket(nt, "same normalized title", (i) => normalizeTitle(i.title) === nt);
   }
-  if (pack.external.length > 0) {
-    parts.push("## External Knowledge\n");
-    parts.push(
-      "Imported Knowledge Capsules \u2014 minimal context about external systems (not their source).\n"
-    );
-    for (const cap of pack.external) {
-      const lines = [`### ${cap.system}`, ""];
-      if (cap.purpose) lines.push(`- Purpose: ${cap.purpose}`);
-      if (cap.capabilities.length) lines.push(`- Capabilities: ${cap.capabilities.join(", ")}`);
-      if (cap.contracts.length) lines.push(`- Contracts: ${cap.contracts.join(", ")}`);
-      if (cap.owner) lines.push(`- Owner: ${cap.owner}`);
-      if (cap.knownRisks.length) lines.push(`- Known risks: ${cap.knownRisks.join("; ")}`);
-      parts.push(lines.join("\n") + "\n");
-    }
+  return groups;
+}
+function first(values) {
+  if (Array.isArray(values)) {
+    const v = values.find((x) => typeof x === "string" && x);
+    return v ? String(v) : void 0;
   }
-  if (pack.graph) {
-    parts.push("## Knowledge Graph\n");
-    parts.push(
-      [
-        "- Available: yes",
-        `- Scope: ${pack.graph.scope}`,
-        `- Nodes: ${pack.graph.nodes}`,
-        `- Edges: ${pack.graph.edges}`,
-        ...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");
+  return typeof values === "string" && values ? values : void 0;
+}
+function toStringArray2(value) {
+  return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
+}
+function loadScan(dir) {
+  const scanPath = join(dir, ".kaddo", "scan.json");
+  if (!exists(scanPath)) return null;
+  try {
+    const parsed = JSON.parse(readFile(scanPath));
+    const detected = parsed.detected ?? {};
+    return {
+      language: first(detected.languages),
+      framework: first(detected.frameworks),
+      packageManager: first(detected.packageManagers),
+      sourceDirectories: toStringArray2(detected.sourceDirectories),
+      migrationDirectories: toStringArray2(detected.migrationDirectories),
+      contractFiles: toStringArray2(detected.contractFiles),
+      infrastructureFiles: toStringArray2(detected.infrastructureFiles)
+    };
+  } catch {
+    return null;
   }
-  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\`)
-`);
+}
+function hasAgents(dir) {
+  const agentsDir = join(dir, ARCH_DIR2, "agents");
+  if (!exists(agentsDir)) return false;
+  function hasAgentMd(d) {
+    for (const e of readDir(d)) {
+      const full = join(d, e);
+      if (isFile(full)) {
+        if (e.endsWith("-agent.md")) return true;
+      } else if (hasAgentMd(full)) {
+        return true;
+      }
     }
+    return false;
   }
-  if (pack.skills.length > 0) {
-    parts.push("## Skills\n");
-    parts.push("Available reusable skills (agents apply these; content is not inlined):\n");
-    parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
-    parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
-  }
-  parts.push("## Missing Context\n");
-  if (missing.length > 0) {
-    parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
-  } else {
-    parts.push("_None \u2014 all expected context is present._\n");
+  return hasAgentMd(agentsDir);
+}
+function buildProjectExplanation(dir) {
+  const config = loadConfig(dir);
+  const project = {
+    name: config?.project.name ?? "unknown",
+    state: config?.project.state ?? "unknown",
+    teamSize: config?.team.size ?? "unknown",
+    structure: config?.project.structure ?? "unknown",
+    language: config ? languageLabel(projectLanguage(config)) : "English"
+  };
+  const scan = loadScan(dir);
+  const stack = scan ? {
+    language: scan.language,
+    framework: scan.framework,
+    packageManager: scan.packageManager,
+    sourceDirectories: scan.sourceDirectories,
+    migrationDirectories: scan.migrationDirectories,
+    contractFiles: scan.contractFiles,
+    infrastructureFiles: scan.infrastructureFiles
+  } : null;
+  const layers = knowledgeLayers(dir);
+  const layerStatus = (name) => layers.find((l) => l.layer === name)?.status ?? "Missing";
+  const knowledge = {
+    hasScan: scan !== null,
+    hasInventory: exists(join(dir, ARCH_DIR2, "inventory.md")),
+    hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
+    hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
+    hasCapabilities: layerStatus("Product") !== "Missing",
+    hasArchitecture: layerStatus("Tech") !== "Missing",
+    hasRoadmap: layerStatus("Delivery") !== "Missing",
+    hasAgents: hasAgents(dir)
+  };
+  const workItemArtifacts = discoverWorkItems(dir);
+  const items = workItemArtifacts.map((a) => ({
+    id: a.id || a.title,
+    title: a.title,
+    type: a.type,
+    status: a.status,
+    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
+    initiative: a.initiative,
+    knowledgeLevel: a.knowledgeLevel,
+    hasOwnership: a.codeGlobs.length > 0,
+    domains: a.domains
+  }));
+  const byState = lifecycleCounts(items.map((i) => i.lifecycle));
+  const byType = {};
+  for (const i of items) {
+    const t = i.type || "unknown";
+    byType[t] = (byType[t] ?? 0) + 1;
   }
-  parts.push("## Recommended Agent Handoff\n");
-  parts.push(`Recommended next for the **${pack.phase.phase}** phase:
-`);
-  parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
-  if (handoff.nextSteps.length > 0) {
-    parts.push("Next step:\n");
-    parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
+  const initiativeMap = /* @__PURE__ */ new Map();
+  for (const i of items) {
+    const name = i.initiative || "Unassigned";
+    if (!initiativeMap.has(name)) initiativeMap.set(name, emptyLifecycleCounts());
+    initiativeMap.get(name)[i.lifecycle]++;
   }
-  parts.push("## Instructions for the LLM\n");
-  parts.push(handoff.instructions.map((i) => `- ${i}`).join("\n") + "\n");
-  return parts.join("\n");
+  const initiatives = [...initiativeMap.entries()].map(([name, states]) => ({ name, states })).sort((a, b) => a.name.localeCompare(b.name));
+  const workItems = {
+    total: items.length,
+    inProgress: items.filter((i) => i.lifecycle === "in-progress").length,
+    done: items.filter((i) => i.status === "done").length,
+    cancelled: items.filter((i) => i.status === "cancelled").length,
+    byState,
+    byType,
+    initiatives,
+    items
+  };
+  const withOwnership = items.filter((i) => i.hasOwnership).length;
+  const ownership = {
+    workItemsTotal: items.length,
+    workItemsWithOwnership: withOwnership,
+    workItemsMissingOwnership: items.length - withOwnership
+  };
+  const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
+  const duplicateWorkItems = findDuplicateWorkItems(
+    workItemArtifacts.map((a) => ({ id: a.id || a.title, title: a.title, sourceId: a.sourceId }))
+  );
+  const roadmapPath = join(dir, ARCH_DIR2, "delivery", "roadmap.md");
+  const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
+  const roadmap = roadmapStats(roadmapMd, items.length);
+  const mappedModules = loadMappedModules(dir);
+  const missingKnowledge = [];
+  if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
+  if (!knowledge.hasContextPack) missingKnowledge.push("Context pack (.kaddo/context-pack.md)");
+  if (!knowledge.hasInventory) missingKnowledge.push("Inventory (knowledge/inventory.md)");
+  if (!knowledge.hasCapabilities) missingKnowledge.push("Product knowledge (knowledge/product/)");
+  if (!knowledge.hasArchitecture) missingKnowledge.push("Tech knowledge (knowledge/tech/)");
+  if (!knowledge.hasRoadmap) missingKnowledge.push("Roadmap (knowledge/delivery/roadmap.md)");
+  if (!knowledge.hasAgents) missingKnowledge.push("Agents (knowledge/agents/)");
+  if (items.length === 0) missingKnowledge.push("Work items (knowledge/delivery/work-items/)");
+  const suggestedNextSteps = [];
+  if (!knowledge.hasScan) {
+    suggestedNextSteps.push("Run `kaddo scan` to detect the technical stack.");
+  } else if (!knowledge.hasContextPack) {
+    suggestedNextSteps.push("Run `kaddo context` to prepare an LLM context pack.");
+  }
+  if (!knowledge.hasAgents) {
+    suggestedNextSteps.push("Run `kaddo add agents` to install knowledge agents.");
+  }
+  if (!knowledge.hasCapabilities) {
+    suggestedNextSteps.push("Use capability-agent to generate knowledge/product/capabilities.md.");
+  }
+  if (!knowledge.hasArchitecture) {
+    suggestedNextSteps.push("Use architecture-agent to generate knowledge/tech/current-state.md.");
+  }
+  if (!knowledge.hasRoadmap) {
+    suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
+  } else if (roadmap.remaining > 0) {
+    suggestedNextSteps.push(
+      `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
+    );
+  }
+  if (items.length === 0 && !roadmap.present) {
+    suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
+  } else if (ownership.workItemsMissingOwnership > 0) {
+    suggestedNextSteps.push(
+      "Run `kaddo owners suggest` for Work Items without code ownership."
+    );
+  }
+  return {
+    project,
+    stack,
+    knowledge,
+    workItems,
+    ownership,
+    domains,
+    duplicateWorkItems,
+    externalCapsules: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
+    graphHints: loadGraphHints(dir),
+    skills: (() => {
+      const installed = discoverInstalledSkills(dir);
+      return { total: installed.length, byGroup: skillGroupCounts(installed) };
+    })(),
+    layers,
+    roadmap,
+    mappedModules,
+    missingKnowledge,
+    suggestedNextSteps
+  };
+}
+function stateLabel(state) {
+  return state === "pre-ai" ? "pre-ai" : state;
+}
+function typeLabel(type) {
+  const cap = type.charAt(0).toUpperCase() + type.slice(1);
+  return cap.endsWith("s") ? cap : `${cap}s`;
+}
+var LIFECYCLE_LABEL = {
+  draft: "Draft",
+  ready: "Ready",
+  "in-progress": "In Progress",
+  blocked: "Blocked",
+  completed: "Completed",
+  archived: "Archived"
+};
+function renderExplanationHuman(exp) {
+  const lines = [];
+  lines.push("# Project Explanation");
+  lines.push("");
+  lines.push("## Project");
+  lines.push(`- Name: ${exp.project.name}`);
+  lines.push(`- State: ${stateLabel(exp.project.state)}`);
+  lines.push(`- Team: ${exp.project.teamSize}`);
+  lines.push(`- Structure: ${exp.project.structure}`);
+  lines.push(`- Project language: ${exp.project.language}`);
+  lines.push("");
+  lines.push("## Knowledge Layers");
+  lines.push(renderLayersMarkdown(exp.layers));
+  lines.push("");
+  if (exp.stack) {
+    lines.push("## Detected Stack");
+    if (exp.stack.language) lines.push(`- Language: ${exp.stack.language}`);
+    if (exp.stack.framework) lines.push(`- Framework: ${exp.stack.framework}`);
+    if (exp.stack.packageManager) lines.push(`- Package manager: ${exp.stack.packageManager}`);
+    if (exp.stack.sourceDirectories.length > 0)
+      lines.push(`- Source: ${exp.stack.sourceDirectories.join(", ")}`);
+    if (exp.stack.migrationDirectories.length > 0)
+      lines.push(`- Migrations: ${exp.stack.migrationDirectories.join(", ")}`);
+    if (exp.stack.infrastructureFiles.length > 0)
+      lines.push(`- Infrastructure: ${exp.stack.infrastructureFiles.join(", ")}`);
+    lines.push("");
+  }
+  const ls = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
+  lines.push("## Knowledge Status");
+  lines.push(`- Inventory: ${exp.knowledge.hasInventory ? "available" : "missing"}`);
+  lines.push(`- Context pack: ${exp.knowledge.hasContextPack ? "available" : "missing"}`);
+  lines.push(`- Business: ${ls("Business")}`);
+  lines.push(`- Product: ${ls("Product")}`);
+  lines.push(`- Tech: ${ls("Tech")}`);
+  lines.push(`- Delivery: ${ls("Delivery")}`);
+  lines.push(`- Agents: ${exp.knowledge.hasAgents ? "available" : "missing"}`);
+  if (exp.roadmap.present) {
+    lines.push(`- Roadmap candidates: ${exp.roadmap.candidates}`);
+    lines.push(`- Materialized work items: ${exp.roadmap.materialized}`);
+    if (exp.roadmap.remaining > 0)
+      lines.push(`- Remaining candidates: ${exp.roadmap.remaining}`);
+  } else {
+    lines.push(`- Work items: ${exp.workItems.total}`);
+  }
+  lines.push(
+    `- Ownership coverage: ${exp.ownership.workItemsWithOwnership}/${exp.ownership.workItemsTotal} work items`
+  );
+  lines.push("");
+  if (exp.workItems.total > 0) {
+    lines.push("## Work Items");
+    for (const s of LIFECYCLE_STATES) {
+      lines.push(`- ${LIFECYCLE_LABEL[s]}: ${exp.workItems.byState[s]}`);
+    }
+    lines.push("");
+    const typeEntries = Object.entries(exp.workItems.byType).sort((a, b) => b[1] - a[1]);
+    if (typeEntries.length > 0) {
+      lines.push("## Work Items by Type");
+      for (const [t, n] of typeEntries) lines.push(`- ${typeLabel(t)}: ${n}`);
+      lines.push("");
+    }
+    const grouped = exp.workItems.initiatives.filter(
+      (g) => LIFECYCLE_STATES.some((s) => g.states[s] > 0)
+    );
+    if (grouped.length > 0) {
+      lines.push("## Work Items by Initiative");
+      for (const g of grouped) {
+        const parts = LIFECYCLE_STATES.filter((s) => g.states[s] > 0).map(
+          (s) => `${LIFECYCLE_LABEL[s]}: ${g.states[s]}`
+        );
+        lines.push(`- ${g.name} \u2014 ${parts.join(" \xB7 ")}`);
+      }
+      lines.push("");
+    }
+  }
+  const active = exp.workItems.items.filter((i) => i.lifecycle === "in-progress");
+  if (active.length > 0) {
+    lines.push("## In Progress");
+    for (const wi of active) {
+      const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
+      const owned = wi.hasOwnership ? " \u25CF" : " \u25CB";
+      lines.push(`-${owned} ${wi.id}${level} \u2014 ${wi.title}`);
+    }
+    lines.push("");
+  }
+  if (exp.domains.length > 0) {
+    lines.push("## Domains");
+    lines.push(`- ${exp.domains.join(", ")}`);
+    lines.push("");
+  }
+  lines.push("## Mapped Modules");
+  if (exp.mappedModules.length > 0) {
+    for (const m of exp.mappedModules) {
+      const owner = m.owner ? ` \u2014 owner: ${m.owner}` : "";
+      lines.push(`- ${m.id} \u2014 ${m.type ?? "unknown"} \u2014 ${m.repoPath || "\u2014"}${owner}`);
+    }
+    lines.push("");
+    lines.push("## Module Artifact Coverage");
+    for (const m of exp.mappedModules) {
+      const present = presentArtifacts(m.artifacts);
+      lines.push(`- ${m.id}: ${present.length > 0 ? present.join(", ") : "none"}`);
+    }
+    lines.push("");
+  } else {
+    lines.push("- Mapped modules: 0");
+    lines.push("");
+  }
+  if (exp.externalCapsules.length > 0) {
+    lines.push(`## External Knowledge Capsules: ${exp.externalCapsules.length}`);
+    for (const cap of exp.externalCapsules) {
+      const owner = cap.owner ? ` \u2014 owner: ${cap.owner}` : "";
+      lines.push(`- ${cap.system}${owner}`);
+      if (cap.ageDays !== null && cap.ageDays >= 90) {
+        lines.push(`  \u26A0 capsule last updated ${cap.ageDays} days ago \u2014 it may be stale.`);
+      }
+    }
+    lines.push("");
+  }
+  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) {
+    lines.push(`## Skills installed: ${exp.skills.total}`);
+    const groups = Object.entries(exp.skills.byGroup).sort((a, b) => a[0].localeCompare(b[0]));
+    if (groups.length > 0) {
+      lines.push("Groups:");
+      for (const [g, n] of groups) lines.push(`- ${g}: ${n}`);
+    }
+    lines.push("");
+  }
+  if (exp.missingKnowledge.length > 0) {
+    lines.push("## Missing Knowledge");
+    for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
+    lines.push("");
+  }
+  if (exp.duplicateWorkItems.length > 0) {
+    lines.push("## Possible Duplicate Work Items");
+    for (const g of exp.duplicateWorkItems) {
+      lines.push(`- ${g.reason}:`);
+      for (const i of g.items) lines.push(`  - ${i.id} \u2014 ${i.title}`);
+    }
+    lines.push("Review before continuing (non-blocking).");
+    lines.push("");
+  }
+  const assessment = assessPhase(exp);
+  lines.push("## Phase");
+  lines.push(`- Phase: ${assessment.phase}`);
+  if (assessment.reasons.length > 0) {
+    lines.push("- Reason:");
+    for (const r of assessment.reasons) lines.push(`  - ${r}`);
+  }
+  if (assessment.nextStep) lines.push(`- Next step: ${assessment.nextStep}`);
+  lines.push("");
+  if (exp.suggestedNextSteps.length > 0) {
+    lines.push("## Suggested Next Steps");
+    exp.suggestedNextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+function renderExplanationAgent(exp) {
+  const { mappedModules, ...rest } = exp;
+  return JSON.stringify({ ...rest, mapped_modules: mappedModules }, null, 2) + "\n";
+}
+
+// ../cli/src/core/impact-report.ts
+var BROAD_GLOB = /^[^/*]+\/\*\*$/;
+function levelFromRatio(r) {
+  if (r >= 0.9) return "Very High";
+  if (r >= 0.7) return "High";
+  if (r >= 0.4) return "Medium";
+  return "Low";
+}
+function hasSection(body, re) {
+  return body.split(/\r?\n/).some((l) => /^#{1,6}\s+/.test(l) && re.test(l));
+}
+function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
+  const exp = buildProjectExplanation(dir);
+  const wis = discoverWorkItems(dir);
+  const total = wis.length;
+  let withOwnership = 0;
+  let withSource = 0;
+  let withInitiative = 0;
+  let withLevel = 0;
+  let withAcceptance = 0;
+  let withDoD = 0;
+  let connectedRoadmap = 0;
+  const globCounts = /* @__PURE__ */ new Map();
+  for (const wi of wis) {
+    if (wi.codeGlobs.length > 0) withOwnership++;
+    const hasSource = Boolean(wi.sourceId) || wi.source === "roadmap";
+    if (hasSource) withSource++;
+    if (hasSource || wi.initiative) connectedRoadmap++;
+    if (wi.initiative) withInitiative++;
+    if (wi.knowledgeLevel) withLevel++;
+    for (const g2 of wi.codeGlobs) globCounts.set(g2, (globCounts.get(g2) ?? 0) + 1);
+    try {
+      const body = matter6(readFile(wi.filePath)).content;
+      if (hasSection(body, /acceptance/i)) withAcceptance++;
+      if (hasSection(body, /definition of done|^#{1,6}\s*done\b/i)) withDoD++;
+    } catch {
+    }
+  }
+  const ownedCodePaths = [...globCounts.values()].reduce((a, b) => a + b, 0);
+  const broadGlobs = [...globCounts.keys()].filter((g2) => BROAD_GLOB.test(g2)).length;
+  const ownershipOverlaps = [...globCounts.values()].filter((n) => n > 1).length;
+  let g;
+  if (opts.scope) {
+    const config = loadConfig(dir);
+    if (config) {
+      const graph = buildGraph(dir, config, { scope: opts.scope }, now);
+      const hints = buildGraphHints(dir, graph, now);
+      g = { available: true, scope: graph.scope, scopeReason: graph.scope_reason, nodes: graph.nodes.length, edges: graph.edges.length, quality: hints.quality, hints: hints.summary.hints, generatedAt: graph.generated_at };
+    } else {
+      g = { available: false, scope: opts.scope, scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
+    }
+  } else if (exp.graph) {
+    g = { available: true, scope: exp.graph.scope, scopeReason: exp.graph.scopeReason, nodes: exp.graph.nodes, edges: exp.graph.edges, quality: exp.graphHints?.quality ?? "unknown", hints: exp.graphHints?.totalHints ?? 0, generatedAt: exp.graph.generatedAt };
+  } else {
+    g = { available: false, scope: "n/a", scopeReason: "", nodes: 0, edges: 0, quality: "unknown", hints: 0, generatedAt: "" };
+  }
+  const layerStatus = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
+  const byState = exp.workItems.byState;
+  const skills = discoverInstalledSkills(dir);
+  const knowledge_health = {
+    Business: layerStatus("Business"),
+    Product: layerStatus("Product"),
+    Tech: layerStatus("Tech"),
+    Delivery: layerStatus("Delivery"),
+    Inventory: exp.knowledge.hasInventory ? "available" : "missing",
+    "Context pack": exp.knowledge.hasContextPack ? "available" : "missing",
+    Agents: exp.knowledge.hasAgents ? "available" : "missing",
+    Skills: skills.length > 0 ? "available" : "missing"
+  };
+  const knowledge_coverage = [
+    { label: "Work Items with ownership", have: withOwnership, total },
+    { label: "Work Items with source", have: withSource, total },
+    { label: "Work Items with initiative", have: withInitiative, total },
+    { label: "Work Items with acceptance criteria", have: withAcceptance, total },
+    { label: "Work Items with Definition of Done", have: withDoD, total },
+    { label: "Work Items with knowledge level", have: withLevel, total }
+  ];
+  const coverageRatio = (have) => total > 0 ? have / total : 0;
+  const deliveryTraceable = ["Traceable", "Structured", "Consolidated"].includes(layerStatus("Delivery"));
+  const ctxReasons = [];
+  let ctxScore = 0;
+  if (["Consolidated", "Structured"].includes(layerStatus("Business"))) {
+    ctxScore++;
+    ctxReasons.push("Business knowledge is present.");
+  }
+  if (["Consolidated", "Structured"].includes(layerStatus("Product"))) {
+    ctxScore++;
+    ctxReasons.push("Product knowledge is present.");
+  }
+  if (layerStatus("Tech") !== "Missing") {
+    ctxScore++;
+    ctxReasons.push("Tech knowledge is structured.");
+  }
+  if (deliveryTraceable) {
+    ctxScore++;
+    ctxReasons.push("Delivery is traceable.");
+  }
+  if (exp.knowledge.hasContextPack) {
+    ctxScore++;
+    ctxReasons.push("Context pack is available.");
+  }
+  if (g.available && g.quality !== "empty") {
+    ctxScore++;
+    ctxReasons.push(`Graph quality is ${g.quality}.`);
+  }
+  const ctxLevel = ctxScore >= 6 ? "Very High" : ctxScore >= 4 ? "High" : ctxScore >= 2 ? "Medium" : "Low";
+  const ambiguityRatio = total > 0 ? (withAcceptance + withDoD + withSource) / (3 * total) : 0;
+  const aiReady = exp.knowledge.hasContextPack && g.available && g.quality !== "empty" && skills.length > 0 && deliveryTraceable ? "High" : exp.knowledge.hasContextPack && g.available && g.quality !== "empty" ? "Medium" : "Low";
+  const onboarding = levelFromRatio(
+    [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * (exp.knowledge.hasContextPack ? 1 : 0.6)
+  );
+  const deliveryTrace = levelFromRatio(
+    coverageRatio(withOwnership) * 0.5 + (g.available && g.edges > 0 ? 1 : 0) * 0.25 + (exp.roadmap.present ? 1 : 0) * 0.25
+  );
+  const impact_signals = {
+    ambiguity_reduction: levelFromRatio(ambiguityRatio),
+    drift_prevention: withOwnership > 0 ? "Active" : "Limited",
+    onboarding_support: onboarding,
+    delivery_traceability: deliveryTrace,
+    ai_context_readiness: aiReady,
+    maintenance_readiness: levelFromRatio((coverageRatio(withOwnership) + (deliveryTraceable ? 1 : 0)) / 2)
+  };
+  let score = null;
+  if (total > 0) {
+    const healthPts = [layerStatus("Business"), layerStatus("Product"), layerStatus("Tech"), layerStatus("Delivery")].filter((s) => s !== "Missing").length / 4 * 20;
+    const covAvg = knowledge_coverage.reduce((a, c) => a + coverageRatio(c.have), 0) / knowledge_coverage.length;
+    const coveragePts = covAvg * 20;
+    const ownPts = coverageRatio(withOwnership) * 15;
+    const traceBlend = (exp.roadmap.candidates > 0 ? exp.roadmap.materialized / exp.roadmap.candidates : 1) * 0.5 + coverageRatio(withOwnership) * 0.5;
+    const tracePts = traceBlend * 20;
+    const qualityMap = { good: 1, partial: 0.6, sparse: 0.3, empty: 0, unknown: 0 };
+    const graphPts = (g.available ? qualityMap[g.quality] ?? 0 : 0) * 15;
+    const ctxPts = { Low: 0.25, Medium: 0.5, High: 0.8, "Very High": 1 }[ctxLevel] * 10;
+    score = Math.round(healthPts + coveragePts + ownPts + tracePts + graphPts + ctxPts);
+  }
+  const actions = [];
+  if (!g.available) actions.push("Run `kaddo graph export --scope all` to inspect full traceability.");
+  else if (g.scope === "active" && g.quality === "empty") actions.push("Run `kaddo graph export --scope all` to include completed Work Items.");
+  if (exp.roadmap.remaining > 0) actions.push(`Materialize the ${exp.roadmap.remaining} remaining roadmap candidate(s) with \`kaddo create --from roadmap\`.`);
+  if (total > 0 && withOwnership < total) actions.push("Add code ownership to Work Items without `code:` globs (`kaddo owners suggest`).");
+  if (total > 0 && withInitiative < total) actions.push("Add an initiative to Work Items missing one.");
+  if (g.available && g.hints > 0) actions.push("Review graph hints (`kaddo://graph-hints` or `.kaddo/graph-hints.md`).");
+  if (skills.length === 0) actions.push("Install reusable skills with `kaddo add skills`.");
+  actions.push("Run `kaddo guard` before committing to catch knowledge drift.");
+  const summary = [];
+  if (total > 0) summary.push(`${withOwnership}/${total} Work Items include code ownership.`);
+  if (g.available) summary.push(`The knowledge graph is ${g.quality} with ${g.nodes} nodes and ${g.edges} edges (${g.scope} scope).`);
+  else summary.push("The knowledge graph has not been exported yet.");
+  if (g.available) summary.push(g.hints === 0 ? "No graph hints are currently open." : `${g.hints} graph hint(s) are open.`);
+  if (exp.roadmap.present) summary.push(`Delivery: ${exp.roadmap.materialized} materialized, ${exp.roadmap.remaining} roadmap candidate(s) remaining.`);
+  summary.push(`Context readiness: ${ctxLevel}.`);
+  return {
+    generated_at: now.toISOString(),
+    project: exp.project.name,
+    scope: g.scope,
+    executive_summary: summary,
+    knowledge_health,
+    knowledge_coverage,
+    ownership_coverage: {
+      coverage_percent: total > 0 ? Math.round(withOwnership / total * 100) : 0,
+      work_items_with_ownership: `${withOwnership}/${total}`,
+      owned_code_paths: ownedCodePaths,
+      broad_globs: broadGlobs,
+      ownership_overlaps: ownershipOverlaps
+    },
+    traceability: {
+      roadmap_candidates: exp.roadmap.candidates,
+      materialized_work_items: exp.roadmap.materialized,
+      remaining_candidates: exp.roadmap.remaining,
+      completed_work_items: byState.completed,
+      work_items_connected_to_roadmap: `${connectedRoadmap}/${total}`,
+      work_items_connected_to_code: `${withOwnership}/${total}`,
+      graph_quality: g.available ? g.quality : "not available",
+      graph_nodes: g.available ? g.nodes : null,
+      graph_edges: g.available ? g.edges : null,
+      graph_hints: g.available ? g.hints : null
+    },
+    context_readiness: { level: ctxLevel, reasons: ctxReasons },
+    work_item_readiness: {
+      draft: byState.draft,
+      ready: byState.ready,
+      in_progress: byState["in-progress"],
+      blocked: byState.blocked,
+      completed: byState.completed,
+      ready_quality: byState.ready > 0 ? `${byState.ready} ready` : "not applicable"
+    },
+    graph_quality: g.available ? { available: true, scope: g.scope, quality: g.quality, nodes: g.nodes, edges: g.edges, hints: g.hints, reason: g.scopeReason, last_exported: g.generatedAt } : { available: false, suggestion: "Run `kaddo graph export --scope all`." },
+    guard_activity: {
+      available: false,
+      note: "Guard history is not persisted. Run `kaddo guard` to check drift; future versions may store runs for trend analysis."
+    },
+    impact_signals,
+    score,
+    suggested_actions: actions
+  };
+}
+function ratio(have, total) {
+  return `${have}/${total}`;
+}
+function renderImpactMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Knowledge Impact Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push(`Scope: ${r.scope}`);
+  if (r.score !== null) L.push(`Knowledge Impact Score: ${r.score}/100`);
+  else L.push("Knowledge Impact Score: not available");
+  L.push("");
+  L.push("## Executive Summary", "");
+  for (const s2 of r.executive_summary) L.push(`- ${s2}`);
+  L.push("");
+  L.push("## Knowledge Health", "");
+  for (const [k, v] of Object.entries(r.knowledge_health)) L.push(`- ${k}: ${v}`);
+  L.push("");
+  L.push("## Knowledge Coverage", "");
+  for (const c of r.knowledge_coverage) L.push(`- ${c.label}: ${ratio(c.have, c.total)}`);
+  L.push("");
+  L.push("## Ownership Coverage", "");
+  L.push(`- Coverage: ${r.ownership_coverage.coverage_percent}%`);
+  L.push(`- Work Items with code ownership: ${r.ownership_coverage.work_items_with_ownership}`);
+  L.push(`- Owned code paths: ${r.ownership_coverage.owned_code_paths}`);
+  L.push(`- Broad globs detected: ${r.ownership_coverage.broad_globs}`);
+  L.push(`- Ownership overlaps: ${r.ownership_coverage.ownership_overlaps}`);
+  L.push("");
+  L.push("## Traceability", "");
+  const t = r.traceability;
+  L.push(`- Roadmap candidates: ${t.roadmap_candidates}`);
+  L.push(`- Materialized Work Items: ${t.materialized_work_items}`);
+  L.push(`- Remaining candidates: ${t.remaining_candidates}`);
+  L.push(`- Completed Work Items: ${t.completed_work_items}`);
+  L.push(`- Work Items connected to roadmap: ${t.work_items_connected_to_roadmap}`);
+  L.push(`- Work Items connected to code: ${t.work_items_connected_to_code}`);
+  L.push(`- Graph quality: ${t.graph_quality}`);
+  if (t.graph_nodes !== null) L.push(`- Graph nodes: ${t.graph_nodes}`);
+  if (t.graph_edges !== null) L.push(`- Graph edges: ${t.graph_edges}`);
+  if (t.graph_hints !== null) L.push(`- Graph hints: ${t.graph_hints}`);
+  L.push("");
+  L.push("## Context Readiness", "");
+  L.push(`Context Readiness: ${r.context_readiness.level}`);
+  if (r.context_readiness.reasons.length > 0) {
+    L.push("", "Reason:");
+    for (const reason of r.context_readiness.reasons) L.push(`- ${reason}`);
+  }
+  L.push("");
+  L.push("## Work Item Readiness", "");
+  const w = r.work_item_readiness;
+  L.push(`- Draft: ${w.draft}`);
+  L.push(`- Ready: ${w.ready}`);
+  L.push(`- In Progress: ${w.in_progress}`);
+  L.push(`- Blocked: ${w.blocked}`);
+  L.push(`- Completed: ${w.completed}`);
+  L.push(`- Ready quality: ${w.ready_quality}`);
+  L.push("");
+  L.push("## Graph Quality", "");
+  if (r.graph_quality.available) {
+    const gq = r.graph_quality;
+    L.push(`- Scope: ${gq.scope}`);
+    L.push(`- Quality: ${gq.quality}`);
+    L.push(`- Nodes: ${gq.nodes}`);
+    L.push(`- Edges: ${gq.edges}`);
+    L.push(`- Hints: ${gq.hints}`);
+    if (gq.reason) L.push(`- Reason: ${gq.reason}`);
+    if (gq.last_exported) L.push(`- Last exported: ${gq.last_exported}`);
+  } else {
+    L.push("- Graph data not available.");
+    L.push(`- Tip: ${r.graph_quality.suggestion}`);
+  }
+  L.push("");
+  L.push("## Guard Activity", "");
+  L.push("- Guard history: not available");
+  L.push(`- Note: ${r.guard_activity.note}`);
+  L.push("");
+  L.push("## Impact Signals", "");
+  const s = r.impact_signals;
+  L.push(`- Ambiguity reduction: ${s.ambiguity_reduction}`);
+  L.push(`- Drift prevention: ${s.drift_prevention}`);
+  L.push(`- Onboarding support: ${s.onboarding_support}`);
+  L.push(`- Delivery traceability: ${s.delivery_traceability}`);
+  L.push(`- AI context readiness: ${s.ai_context_readiness}`);
+  L.push(`- Maintenance readiness: ${s.maintenance_readiness}`);
+  L.push("");
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+  L.push("");
+  return L.join("\n");
+}
+function serializeImpactJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+
+// src/workitems.ts
+import matter7 from "gray-matter";
+var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
+function strArray(v) {
+  return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
+}
+function lifecycleOf(data, relPath) {
+  const status = String(data.status ?? "").trim();
+  if (status) return status;
+  const segs = relPath.split("/");
+  const folder = segs[segs.length - 2];
+  return ACTIVE_STATES2.has(folder) || folder === "completed" || folder === "archived" ? folder : "ready";
+}
+function firstParagraph2(body) {
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
+  }
+  return "";
+}
+function listWorkItems(root) {
+  const files = listFiles(root, "knowledge/delivery/work-items", ".md");
+  const items = [];
+  for (const rel of files) {
+    const raw = readText(root, rel);
+    if (raw === null) continue;
+    let parsed;
+    try {
+      parsed = matter7(raw);
+    } catch {
+      continue;
+    }
+    const data = parsed.data;
+    if (!data.type) continue;
+    items.push({
+      id: String(data.id ?? "") || rel,
+      title: String(data.title ?? ""),
+      status: lifecycleOf(data, rel),
+      type: String(data.type ?? ""),
+      knowledge_level: String(data.knowledge_level ?? ""),
+      path: rel,
+      summary: String(data.summary ?? "") || firstParagraph2(parsed.content),
+      code: strArray(data.code),
+      capabilities: strArray(data.capabilities),
+      decisions: strArray(data.decisions),
+      capsules: strArray(data.capsules)
+    });
+  }
+  return items.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// src/resources.ts
+function text(uri, body, mimeType = "text/markdown") {
+  return [{ uri, text: body, mimeType }];
+}
+function fileOrHint(root, uri, rel, hint, mimeType = "text/markdown") {
+  const body = readText(root, rel);
+  return text(uri, body ?? hint, body ? mimeType : "text/plain");
+}
+var RESOURCES = [
+  {
+    uri: "kaddo://context-pack",
+    name: "Kaddo context pack",
+    description: "Curated LLM context pack (.kaddo/context-pack.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://context-pack",
+      ".kaddo/context-pack.md",
+      "Context pack not found. Run `kaddo context` in the project first."
+    )
+  },
+  {
+    uri: "kaddo://explain",
+    name: "Kaddo explain",
+    description: "What Kaddo knows about the project (.kaddo/explain.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://explain",
+      ".kaddo/explain.md",
+      "Explain output not found. Run `kaddo explain` first."
+    )
+  },
+  {
+    uri: "kaddo://understand",
+    name: "Kaddo understand",
+    description: "Current phase and recommended next step (.kaddo/understand.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://understand",
+      ".kaddo/understand.md",
+      "Understand output not found. Run `kaddo understand` first."
+    )
+  },
+  {
+    uri: "kaddo://graph",
+    name: "Kaddo knowledge graph",
+    description: "Knowledge graph (.kaddo/graph.json + .kaddo/graph.mmd).",
+    mimeType: "application/json",
+    read: (root) => {
+      const json = readText(root, ".kaddo/graph.json");
+      const mmd = readText(root, ".kaddo/graph.mmd");
+      if (!json && !mmd) {
+        return text("kaddo://graph", "Knowledge graph not found. Run `kaddo graph export` first.", "text/plain");
+      }
+      const parts = [];
+      if (json) parts.push({ uri: "kaddo://graph", text: json, mimeType: "application/json" });
+      if (mmd) parts.push({ uri: "kaddo://graph.mmd", text: mmd, mimeType: "text/vnd.mermaid" });
+      return parts;
+    }
+  },
+  {
+    uri: "kaddo://graph-hints",
+    name: "Kaddo graph hints",
+    description: "Graph relationship-quality hints (.kaddo/graph-hints.md + .json).",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const md = readText(root, ".kaddo/graph-hints.md");
+      const json = readText(root, ".kaddo/graph-hints.json");
+      if (!md && !json) {
+        return text("kaddo://graph-hints", "Graph hints not found. Run `kaddo graph export` first.", "text/plain");
+      }
+      const parts = [];
+      if (md) parts.push({ uri: "kaddo://graph-hints", text: md, mimeType: "text/markdown" });
+      if (json) parts.push({ uri: "kaddo://graph-hints.json", text: json, mimeType: "application/json" });
+      return parts;
+    }
+  },
+  {
+    uri: "kaddo://work-items",
+    name: "Kaddo work items",
+    description: "Summarized Work Items from knowledge/delivery/work-items/.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://work-items", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [
+        {
+          uri: "kaddo://work-items",
+          text: JSON.stringify(listWorkItems(root), null, 2),
+          mimeType: "application/json"
+        }
+      ];
+    }
+  },
+  {
+    uri: "kaddo://roadmap",
+    name: "Kaddo roadmap",
+    description: "Delivery roadmap (knowledge/delivery/roadmap.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://roadmap",
+      "knowledge/delivery/roadmap.md",
+      "Roadmap not found. Create knowledge/delivery/roadmap.md (e.g. via the roadmap-agent) first."
+    )
+  },
+  {
+    uri: "kaddo://capsules",
+    name: "Kaddo knowledge capsules",
+    description: "External Knowledge Capsules from .kaddo/external.yml and external/.",
+    mimeType: "application/json",
+    read: (root) => [
+      {
+        uri: "kaddo://capsules",
+        text: JSON.stringify(listCapsules(root), null, 2),
+        mimeType: "application/json"
+      }
+    ]
+  },
+  {
+    uri: "kaddo://agents",
+    name: "Kaddo agents",
+    description: "Installed agent prompts from knowledge/agents/.",
+    mimeType: "application/json",
+    read: (root) => [
+      {
+        uri: "kaddo://agents",
+        text: JSON.stringify(listAgents(root), null, 2),
+        mimeType: "application/json"
+      }
+    ]
+  },
+  {
+    uri: "kaddo://skills",
+    name: "Kaddo skills",
+    description: "Installed reusable skills from knowledge/skills/ (empty if none).",
+    mimeType: "application/json",
+    read: (root) => [
+      {
+        uri: "kaddo://skills",
+        text: JSON.stringify({ skills: listSkills(root) }, null, 2),
+        mimeType: "application/json"
+      }
+    ]
+  },
+  {
+    uri: "kaddo://impact-report",
+    name: "Kaddo impact report",
+    description: "Knowledge Impact Report \u2014 the last written report, or generated in memory (read-only).",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const saved = readText(root, ".kaddo/reports/impact-report.md");
+      if (saved) return [{ uri: "kaddo://impact-report", text: saved, mimeType: "text/markdown" }];
+      if (!hasKnowledge(root)) {
+        return text("kaddo://impact-report", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [{ uri: "kaddo://impact-report", text: renderImpactMarkdown(buildImpactReport(root, { scope: "all" })), mimeType: "text/markdown" }];
+    }
+  }
+];
+
+// src/prompts.ts
+var EXTRA_INPUTS = {
+  "graph-agent": [".kaddo/graph.json", ".kaddo/graph-hints.md"],
+  "ownership-agent": ["knowledge/delivery/work-items/", "knowledge/inventory.md"],
+  "capsule-agent": ["knowledge/product/capabilities.md", "knowledge/tech/decisions/"],
+  "work-item-agent": ["knowledge/delivery/roadmap.md"],
+  "implementation-agent": ["knowledge/tech/git-strategy.md"]
+};
+function recommendedInputs(name) {
+  return [".kaddo/context-pack.md", ...EXTRA_INPUTS[name] ?? []];
+}
+function listPrompts(root) {
+  return listAgents(root).map((a) => ({
+    name: a.name,
+    description: a.description || `Kaddo ${a.name}`,
+    content: "",
+    recommended_inputs: recommendedInputs(a.name)
+  }));
+}
+function getPrompt(root, name) {
+  const agent = getAgentPrompt(root, name);
+  if (!agent) return null;
+  return {
+    name: agent.name,
+    description: agent.description || `Kaddo ${agent.name}`,
+    content: agent.content,
+    recommended_inputs: recommendedInputs(agent.name)
+  };
+}
+
+// src/tools.ts
+var ok = (data) => ({ ok: true, data });
+var fail = (message) => ({ ok: false, message });
+function projectStatus(root) {
+  const explain = readJson(root, ".kaddo/explain.json");
+  const hints = readJson(root, ".kaddo/graph-hints.json");
+  const capsules = listCapsules(root);
+  if (!explain) {
+    return fail("Project status needs `.kaddo/explain.json`. Run `kaddo explain` first.");
+  }
+  const maturity = (explain.layers ?? []).map((l) => `${l.layer}: ${l.status}`);
+  return ok({
+    project: explain.project?.name ?? "unknown",
+    state: explain.project?.state ?? "unknown",
+    knowledgeMaturity: maturity,
+    workItems: {
+      total: explain.workItems?.total ?? 0,
+      byState: explain.workItems?.byState ?? {},
+      byType: explain.workItems?.byType ?? {}
+    },
+    ownership: {
+      withOwnership: explain.ownership?.workItemsWithOwnership ?? 0,
+      total: explain.ownership?.workItemsTotal ?? 0
+    },
+    graph: {
+      scope: hints?.scope ?? "unknown (run `kaddo graph export`)",
+      scope_reason: hints?.scope_reason ?? "",
+      quality: hints?.quality ?? "unknown (run `kaddo graph export`)",
+      hints: hints?.summary?.hints ?? 0
+    },
+    capsules: capsules.length
+  });
+}
+function listWorkItemsTool(root, filter = {}) {
+  let items = listWorkItems(root);
+  if (filter.status) items = items.filter((w) => w.status === filter.status);
+  if (filter.type) items = items.filter((w) => w.type === filter.type);
+  if (filter.knowledge_level) items = items.filter((w) => w.knowledge_level === filter.knowledge_level);
+  return ok(items);
 }
-
-// ../cli/src/core/project-explain.ts
-var ARCH_DIR3 = "knowledge";
-function normalizeTitle(t) {
-  return t.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+function getWorkItem(root, id) {
+  const item = listWorkItems(root).find((w) => w.id === id);
+  if (!item) return fail(`Work Item "${id}" not found.`);
+  const content = readText(root, item.path);
+  return ok({ ...item, content: content ?? "" });
 }
-function findDuplicateWorkItems(items) {
-  const groups = [];
-  const seen = /* @__PURE__ */ new Set();
-  const bucket = (key, reason, pred) => {
-    const matched = items.filter(pred);
-    if (matched.length > 1) {
-      const id = `${reason}:${key}:${matched.map((m) => m.id).sort().join(",")}`;
-      if (!seen.has(id)) {
-        seen.add(id);
-        groups.push({ reason, items: matched.map((m) => ({ id: m.id, title: m.title })) });
-      }
-    }
-  };
-  for (const sid of new Set(items.map((i) => i.sourceId).filter(Boolean))) {
-    bucket(sid, `same source candidate (${sid})`, (i) => i.sourceId === sid);
-  }
-  for (const nt of new Set(items.map((i) => normalizeTitle(i.title)).filter(Boolean))) {
-    bucket(nt, "same normalized title", (i) => normalizeTitle(i.title) === nt);
-  }
-  return groups;
+function listCapsulesTool(root) {
+  return ok(listCapsules(root));
 }
-function first(values) {
-  if (Array.isArray(values)) {
-    const v = values.find((x) => typeof x === "string" && x);
-    return v ? String(v) : void 0;
-  }
-  return typeof values === "string" && values ? values : void 0;
+function getCapsuleTool(root, id) {
+  const cap = getCapsule(root, id);
+  if (!cap) return fail(`Knowledge Capsule "${id}" not found.`);
+  return ok(cap);
 }
-function toStringArray2(value) {
-  return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
+function listAgentsTool(root) {
+  return ok(listAgents(root));
 }
-function loadScan(dir) {
+function getAgentPromptTool(root, name) {
+  const agent = getAgentPrompt(root, name);
+  if (!agent) return fail(`Agent "${name}" is not installed. Run \`kaddo add agents\` first.`);
+  return ok(agent);
+}
+function listSkillsTool(root) {
+  return ok(listSkills(root));
+}
+function getSkillTool(root, id) {
+  const skill = getSkill(root, id);
+  if (!skill) return fail(`Skill "${id}" is not installed. Run \`kaddo add skills\` first.`);
+  return ok(skill);
+}
+function listGraphHints(root, filter = {}) {
+  const report = readJson(root, ".kaddo/graph-hints.json");
+  if (!report) return fail("Graph hints not found. Run `kaddo graph export` first.");
+  let hints = Array.isArray(report.hints) ? report.hints : [];
+  if (filter.artifact_type) hints = hints.filter((h) => h.artifact_type === filter.artifact_type);
+  if (filter.severity) hints = hints.filter((h) => h.severity === filter.severity);
+  if (filter.active_only) hints = hints.filter((h) => h.artifact_type === "work-item");
+  return ok({
+    scope: report.scope ?? "active",
+    scope_reason: report.scope_reason ?? "",
+    quality: report.quality ?? "unknown",
+    count: hints.length,
+    hints
+  });
+}
+
+// ../cli/src/core/context-pack.ts
+import matter8 from "gray-matter";
+var CONTEXT_PACK_VERSION = "1";
+var ARCH_DIR3 = "knowledge";
+function readScanJson(dir) {
   const scanPath = join(dir, ".kaddo", "scan.json");
   if (!exists(scanPath)) return null;
   try {
-    const parsed = JSON.parse(readFile(scanPath));
-    const detected = parsed.detected ?? {};
-    return {
-      language: first(detected.languages),
-      framework: first(detected.frameworks),
-      packageManager: first(detected.packageManagers),
-      sourceDirectories: toStringArray2(detected.sourceDirectories),
-      migrationDirectories: toStringArray2(detected.migrationDirectories),
-      contractFiles: toStringArray2(detected.contractFiles),
-      infrastructureFiles: toStringArray2(detected.infrastructureFiles)
-    };
+    return JSON.parse(readFile(scanPath));
   } catch {
     return null;
   }
 }
-function hasAgents(dir) {
-  const agentsDir = join(dir, ARCH_DIR3, "agents");
-  if (!exists(agentsDir)) return false;
-  function hasAgentMd(d) {
-    for (const e of readDir(d)) {
-      const full = join(d, e);
-      if (isFile(full)) {
-        if (e.endsWith("-agent.md")) return true;
-      } else if (hasAgentMd(full)) {
-        return true;
-      }
-    }
-    return false;
+function firstParagraph3(markdown) {
+  const body = matter8(markdown).content.trim();
+  const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
+  return para ?? "";
+}
+function readMarkdownSummary(dir, file) {
+  const p = join(dir, ARCH_DIR3, file);
+  if (!exists(p)) return null;
+  try {
+    return firstParagraph3(readFile(p));
+  } catch {
+    return null;
   }
-  return hasAgentMd(agentsDir);
 }
-function buildProjectExplanation(dir) {
-  const config = loadConfig(dir);
-  const project = {
-    name: config?.project.name ?? "unknown",
-    state: config?.project.state ?? "unknown",
-    teamSize: config?.team.size ?? "unknown",
-    structure: config?.project.structure ?? "unknown",
-    language: config ? languageLabel(projectLanguage(config)) : "English"
-  };
-  const scan = loadScan(dir);
-  const stack = scan ? {
-    language: scan.language,
-    framework: scan.framework,
-    packageManager: scan.packageManager,
-    sourceDirectories: scan.sourceDirectories,
-    migrationDirectories: scan.migrationDirectories,
-    contractFiles: scan.contractFiles,
-    infrastructureFiles: scan.infrastructureFiles
-  } : null;
-  const layers = knowledgeLayers(dir);
-  const layerStatus = (name) => layers.find((l) => l.layer === name)?.status ?? "Missing";
-  const knowledge = {
-    hasScan: scan !== null,
-    hasInventory: exists(join(dir, ARCH_DIR3, "inventory.md")),
-    hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
-    hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
-    hasCapabilities: layerStatus("Product") !== "Missing",
-    hasArchitecture: layerStatus("Tech") !== "Missing",
-    hasRoadmap: layerStatus("Delivery") !== "Missing",
-    hasAgents: hasAgents(dir)
-  };
-  const workItemArtifacts = discoverWorkItems(dir);
-  const items = workItemArtifacts.map((a) => ({
-    id: a.id || a.title,
-    title: a.title,
-    type: a.type,
-    status: a.status,
-    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
-    initiative: a.initiative,
-    knowledgeLevel: a.knowledgeLevel,
-    hasOwnership: a.codeGlobs.length > 0,
-    domains: a.domains
-  }));
-  const byState = lifecycleCounts(items.map((i) => i.lifecycle));
-  const byType = {};
-  for (const i of items) {
-    const t = i.type || "unknown";
-    byType[t] = (byType[t] ?? 0) + 1;
+function recommendedAgentsForState(state) {
+  switch (state) {
+    case "new":
+      return ["roadmap-agent", "architecture-agent"];
+    case "legacy":
+      return ["legacy-agent", "architecture-agent", "capability-agent"];
+    case "pre-ai":
+    default:
+      return ["capability-agent", "architecture-agent", "roadmap-agent"];
   }
-  const initiativeMap = /* @__PURE__ */ new Map();
-  for (const i of items) {
-    const name = i.initiative || "Unassigned";
-    if (!initiativeMap.has(name)) initiativeMap.set(name, emptyLifecycleCounts());
-    initiativeMap.get(name)[i.lifecycle]++;
+}
+function nextStepsForState(state) {
+  switch (state) {
+    case "new":
+      return [
+        "Use roadmap-agent to shape an initial roadmap.",
+        "Use architecture-agent to outline the intended architecture."
+      ];
+    case "legacy":
+      return [
+        "Use legacy-agent to surface risks and unknowns before changing code.",
+        "Use architecture-agent to reconstruct the current architecture.",
+        "Use capability-agent to map existing capabilities."
+      ];
+    case "pre-ai":
+    default:
+      return [
+        "Use capability-agent to extract system capabilities.",
+        "Use architecture-agent to reconstruct the current architecture.",
+        "Use roadmap-agent to propose roadmap candidates."
+      ];
   }
-  const initiatives = [...initiativeMap.entries()].map(([name, states]) => ({ name, states })).sort((a, b) => a.name.localeCompare(b.name));
-  const workItems = {
-    total: items.length,
-    inProgress: items.filter((i) => i.lifecycle === "in-progress").length,
-    done: items.filter((i) => i.status === "done").length,
-    cancelled: items.filter((i) => i.status === "cancelled").length,
-    byState,
-    byType,
-    initiatives,
-    items
-  };
-  const withOwnership = items.filter((i) => i.hasOwnership).length;
-  const ownership = {
-    workItemsTotal: items.length,
-    workItemsWithOwnership: withOwnership,
-    workItemsMissingOwnership: items.length - withOwnership
-  };
-  const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
-  const duplicateWorkItems = findDuplicateWorkItems(
-    workItemArtifacts.map((a) => ({ id: a.id || a.title, title: a.title, sourceId: a.sourceId }))
-  );
-  const roadmapPath = join(dir, ARCH_DIR3, "delivery", "roadmap.md");
-  const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
-  const roadmap = roadmapStats(roadmapMd, items.length);
-  const mappedModules = loadMappedModules(dir);
-  const missingKnowledge = [];
-  if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
-  if (!knowledge.hasContextPack) missingKnowledge.push("Context pack (.kaddo/context-pack.md)");
-  if (!knowledge.hasInventory) missingKnowledge.push("Inventory (knowledge/inventory.md)");
-  if (!knowledge.hasCapabilities) missingKnowledge.push("Product knowledge (knowledge/product/)");
-  if (!knowledge.hasArchitecture) missingKnowledge.push("Tech knowledge (knowledge/tech/)");
-  if (!knowledge.hasRoadmap) missingKnowledge.push("Roadmap (knowledge/delivery/roadmap.md)");
-  if (!knowledge.hasAgents) missingKnowledge.push("Agents (knowledge/agents/)");
-  if (items.length === 0) missingKnowledge.push("Work items (knowledge/delivery/work-items/)");
-  const suggestedNextSteps = [];
-  if (!knowledge.hasScan) {
-    suggestedNextSteps.push("Run `kaddo scan` to detect the technical stack.");
-  } else if (!knowledge.hasContextPack) {
-    suggestedNextSteps.push("Run `kaddo context` to prepare an LLM context pack.");
+}
+var LLM_INSTRUCTIONS = [
+  "Use this context pack as the project baseline.",
+  "Do not write code yet.",
+  "First extract: system capabilities, architecture notes, risks, open questions and roadmap candidates.",
+  "This pack is deterministic CLI output \u2014 it does not interpret the system. That is your job."
+];
+var OPERATING_RULES = [
+  "**Never run `git commit`, `git push` or `git merge` without explicit human confirmation.**",
+  "Never push or merge automatically \u2014 ever. Suggest a Conventional Commit message and wait.",
+  "When implementing a Work Item, create a branch FIRST (per the project Git strategy, `.kaddo/git.yml`, default `feature/<id>-<slug>`). Never work directly on `main`.",
+  "After significant changes run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`, and update the affected knowledge (ADR / capabilities / current-state).",
+  "Kaddo itself never calls an LLM and never runs git \u2014 every git action is the human\u2019s."
+];
+function toContextWorkItem(a) {
+  return {
+    id: a.id,
+    type: a.type,
+    title: a.title,
+    status: a.status,
+    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
+    knowledgeLevel: a.knowledgeLevel,
+    domains: a.domains
+  };
+}
+function toContextArtifact(a) {
+  return { id: a.id, type: a.type, title: a.title, summary: a.summary, codeGlobs: a.codeGlobs };
+}
+function isDeliveryWorkItem(a) {
+  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
+}
+function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
+  const missing = [];
+  const scanJson = readScanJson(dir);
+  if (!scanJson) {
+    missing.push("Scan baseline missing. Run `kaddo scan` for better context.");
   }
-  if (!knowledge.hasAgents) {
-    suggestedNextSteps.push("Run `kaddo add agents` to install knowledge agents.");
+  const detected = scanJson?.detected ?? {};
+  const inventoryAvailable = exists(join(dir, ARCH_DIR3, "inventory.md"));
+  if (!inventoryAvailable) {
+    missing.push("No technical inventory found. Run `kaddo scan` to generate it.");
   }
-  if (!knowledge.hasCapabilities) {
-    suggestedNextSteps.push("Use capability-agent to generate knowledge/product/capabilities.md.");
+  const knowledgeSummary = readMarkdownSummary(dir, "knowledge.md") ?? "";
+  if (!knowledgeSummary) {
+    missing.push("No project knowledge summary found yet.");
   }
-  if (!knowledge.hasArchitecture) {
-    suggestedNextSteps.push("Use architecture-agent to generate knowledge/tech/current-state.md.");
+  const roadmapSummary = readMarkdownSummary(dir, "delivery/roadmap.md") ?? "";
+  if (!roadmapSummary) {
+    missing.push("No roadmap baseline found.");
   }
-  if (!knowledge.hasRoadmap) {
-    suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
-  } else if (roadmap.remaining > 0) {
-    suggestedNextSteps.push(
-      `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
-    );
+  const allArtifacts = discoverKnowledge(dir);
+  const workItems = allArtifacts.filter(
+    (a) => isDeliveryWorkItem(a) && isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))
+  );
+  if (workItems.length === 0) {
+    missing.push("No work items found.");
   }
-  if (items.length === 0 && !roadmap.present) {
-    suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
-  } else if (ownership.workItemsMissingOwnership > 0) {
-    suggestedNextSteps.push(
-      "Run `kaddo owners suggest` for Work Items without code ownership."
-    );
+  const state = config.project.state;
+  const roadmapPath = join(dir, ARCH_DIR3, "delivery", "roadmap.md");
+  const materialized = allArtifacts.filter(
+    (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
+  ).length;
+  const roadmap = roadmapStats(exists(roadmapPath) ? readFile(roadmapPath) : null, materialized);
+  const deliveryMix = {};
+  for (const a of allArtifacts) {
+    const p = a.filePath.replace(/\\/g, "/");
+    if (!a.type || !p.includes("/delivery/work-items/")) continue;
+    if (!isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))) continue;
+    deliveryMix[a.type] = (deliveryMix[a.type] ?? 0) + 1;
   }
+  const mappedModules = loadMappedModules(dir);
+  const layers = knowledgeLayers(dir);
+  const allWorkItems = allArtifacts.filter((a) => a.isWorkItem);
+  const wiWithOwnership = allWorkItems.filter((a) => a.codeGlobs.length > 0).length;
+  const phase = assessPhase({
+    layers,
+    roadmap,
+    workItems: {
+      total: allWorkItems.length,
+      byState: lifecycleCounts(
+        allWorkItems.map((a) => lifecycleStateOf({ status: a.status, filePath: a.filePath }))
+      ),
+      items: allWorkItems.map((a) => ({
+        id: a.id || a.title,
+        title: a.title,
+        lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath })
+      }))
+    },
+    ownership: {
+      workItemsTotal: allWorkItems.length,
+      workItemsWithOwnership: wiWithOwnership,
+      workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
+    }
+  });
   return {
-    project,
-    stack,
-    knowledge,
-    workItems,
-    ownership,
-    domains,
-    duplicateWorkItems,
-    externalCapsules: loadExternalCapsules(dir),
-    graph: loadGraphSummary(dir),
-    graphHints: loadGraphHints(dir),
-    skills: (() => {
-      const installed = discoverInstalledSkills(dir);
-      return { total: installed.length, byGroup: skillGroupCounts(installed) };
-    })(),
+    version: CONTEXT_PACK_VERSION,
+    generatedAt: now.toISOString(),
+    project: {
+      name: config.project.name,
+      state,
+      teamSize: config.team.size,
+      structure: config.project.structure,
+      language: languageLabel(projectLanguage(config))
+    },
+    scan: {
+      available: scanJson !== null,
+      languages: detected.languages ?? [],
+      frameworks: detected.frameworks ?? [],
+      packageManagers: detected.packageManagers ?? [],
+      sourceDirectories: detected.sourceDirectories ?? [],
+      migrationDirectories: detected.migrationDirectories ?? [],
+      contractFiles: detected.contractFiles ?? [],
+      infrastructureFiles: detected.infrastructureFiles ?? []
+    },
+    knowledge: {
+      summary: knowledgeSummary,
+      roadmapSummary,
+      inventoryAvailable,
+      workItems: workItems.map(toContextWorkItem),
+      artifacts: allArtifacts.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
+    },
     layers,
     roadmap,
+    phase,
+    deliveryMix,
+    external: loadExternalCapsules(dir),
+    graph: loadGraphSummary(dir),
+    graphHints: loadGraphHints(dir),
+    skills: discoverInstalledSkills(dir).map((s) => s.id),
     mappedModules,
-    missingKnowledge,
-    suggestedNextSteps
+    missing,
+    // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
+    // contradicts the Current Phase block above it.
+    handoff: {
+      recommendedAgents: phase.recommendedAgents.length > 0 ? phase.recommendedAgents : recommendedAgentsForState(state),
+      nextSteps: phase.nextStep ? [phase.nextStep] : nextStepsForState(state),
+      instructions: phase.llmInstructions.length > 0 ? phase.llmInstructions : LLM_INSTRUCTIONS,
+      operatingRules: OPERATING_RULES
+    }
   };
 }
-function stateLabel(state) {
-  return state === "pre-ai" ? "pre-ai" : state;
-}
-function typeLabel(type) {
-  const cap = type.charAt(0).toUpperCase() + type.slice(1);
-  return cap.endsWith("s") ? cap : `${cap}s`;
+function serializeContextPackJson(pack) {
+  return JSON.stringify(pack, null, 2) + "\n";
 }
-var LIFECYCLE_LABEL = {
-  draft: "Draft",
-  ready: "Ready",
-  "in-progress": "In Progress",
-  blocked: "Blocked",
-  completed: "Completed",
-  archived: "Archived"
-};
-function renderExplanationHuman(exp) {
-  const lines = [];
-  lines.push("# Project Explanation");
-  lines.push("");
-  lines.push("## Project");
-  lines.push(`- Name: ${exp.project.name}`);
-  lines.push(`- State: ${stateLabel(exp.project.state)}`);
-  lines.push(`- Team: ${exp.project.teamSize}`);
-  lines.push(`- Structure: ${exp.project.structure}`);
-  lines.push(`- Project language: ${exp.project.language}`);
-  lines.push("");
-  lines.push("## Knowledge Layers");
-  lines.push(renderLayersMarkdown(exp.layers));
-  lines.push("");
-  if (exp.stack) {
-    lines.push("## Detected Stack");
-    if (exp.stack.language) lines.push(`- Language: ${exp.stack.language}`);
-    if (exp.stack.framework) lines.push(`- Framework: ${exp.stack.framework}`);
-    if (exp.stack.packageManager) lines.push(`- Package manager: ${exp.stack.packageManager}`);
-    if (exp.stack.sourceDirectories.length > 0)
-      lines.push(`- Source: ${exp.stack.sourceDirectories.join(", ")}`);
-    if (exp.stack.migrationDirectories.length > 0)
-      lines.push(`- Migrations: ${exp.stack.migrationDirectories.join(", ")}`);
-    if (exp.stack.infrastructureFiles.length > 0)
-      lines.push(`- Infrastructure: ${exp.stack.infrastructureFiles.join(", ")}`);
-    lines.push("");
+
+// ../cli/src/templates/context-pack-template.ts
+function renderContextPack(pack) {
+  const { project, scan, knowledge, missing, handoff } = pack;
+  const parts = [];
+  parts.push("# Kaddo Context Pack\n");
+  parts.push(
+    "> Generated by `kaddo context`. Deterministic CLI output \u2014 not an interpretation of the system.\n"
+  );
+  parts.push("## Operating Rules (read first)\n");
+  parts.push(handoff.operatingRules.map((r) => `- ${r}`).join("\n") + "\n");
+  parts.push("## Project Metadata\n");
+  parts.push(
+    [
+      `- Name: ${project.name}`,
+      `- State: ${project.state}`,
+      `- Team size: ${project.teamSize}`,
+      `- Structure: ${project.structure}`,
+      `- Language: ${project.language}`
+    ].join("\n") + "\n"
+  );
+  parts.push("## Current Phase\n");
+  parts.push(`Phase: ${pack.phase.phase}
+`);
+  if (pack.phase.reasons.length > 0) {
+    parts.push("Reason:\n");
+    parts.push(pack.phase.reasons.map((r) => `- ${r}`).join("\n") + "\n");
   }
-  const ls = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
-  lines.push("## Knowledge Status");
-  lines.push(`- Inventory: ${exp.knowledge.hasInventory ? "available" : "missing"}`);
-  lines.push(`- Context pack: ${exp.knowledge.hasContextPack ? "available" : "missing"}`);
-  lines.push(`- Business: ${ls("Business")}`);
-  lines.push(`- Product: ${ls("Product")}`);
-  lines.push(`- Tech: ${ls("Tech")}`);
-  lines.push(`- Delivery: ${ls("Delivery")}`);
-  lines.push(`- Agents: ${exp.knowledge.hasAgents ? "available" : "missing"}`);
-  if (exp.roadmap.present) {
-    lines.push(`- Roadmap candidates: ${exp.roadmap.candidates}`);
-    lines.push(`- Materialized work items: ${exp.roadmap.materialized}`);
-    if (exp.roadmap.remaining > 0)
-      lines.push(`- Remaining candidates: ${exp.roadmap.remaining}`);
-  } else {
-    lines.push(`- Work items: ${exp.workItems.total}`);
+  if (pack.phase.recommendedAgents.length > 0) {
+    parts.push(`Recommended next: ${pack.phase.recommendedAgents.join(", ")}
+`);
   }
-  lines.push(
-    `- Ownership coverage: ${exp.ownership.workItemsWithOwnership}/${exp.ownership.workItemsTotal} work items`
+  if (pack.phase.nextStep) {
+    parts.push(`Next step: ${pack.phase.nextStep}
+`);
+  }
+  parts.push("## Knowledge Layers\n");
+  parts.push(
+    "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
   );
-  lines.push("");
-  if (exp.workItems.total > 0) {
-    lines.push("## Work Items");
-    for (const s of LIFECYCLE_STATES) {
-      lines.push(`- ${LIFECYCLE_LABEL[s]}: ${exp.workItems.byState[s]}`);
+  const maturity = pack.layers.map((l) => `${l.layer}: ${l.status}`).join(" \xB7 ");
+  parts.push(`Knowledge maturity \u2014 ${maturity}
+`);
+  parts.push(renderLayersMarkdown(pack.layers) + "\n");
+  parts.push("## Technical Inventory\n");
+  if (scan.available) {
+    const lines = [
+      `- Language: ${scan.languages.join(", ") || "unknown"}`,
+      `- Framework: ${scan.frameworks.join(", ") || "unknown"}`,
+      `- Package manager: ${scan.packageManagers.join(", ") || "unknown"}`
+    ];
+    if (scan.sourceDirectories.length > 0) {
+      lines.push("- Source directories:");
+      scan.sourceDirectories.forEach((d) => lines.push(`  - ${d}`));
     }
-    lines.push("");
-    const typeEntries = Object.entries(exp.workItems.byType).sort((a, b) => b[1] - a[1]);
-    if (typeEntries.length > 0) {
-      lines.push("## Work Items by Type");
-      for (const [t, n] of typeEntries) lines.push(`- ${typeLabel(t)}: ${n}`);
-      lines.push("");
+    if (scan.migrationDirectories.length > 0) {
+      lines.push("- Migration directories:");
+      scan.migrationDirectories.forEach((d) => lines.push(`  - ${d}`));
     }
-    const grouped = exp.workItems.initiatives.filter(
-      (g) => LIFECYCLE_STATES.some((s) => g.states[s] > 0)
+    if (scan.contractFiles.length > 0) {
+      lines.push("- Contracts:");
+      scan.contractFiles.forEach((f) => lines.push(`  - ${f}`));
+    }
+    if (scan.infrastructureFiles.length > 0) {
+      lines.push("- Infrastructure:");
+      scan.infrastructureFiles.forEach((f) => lines.push(`  - ${f}`));
+    }
+    parts.push(lines.join("\n") + "\n");
+  } else {
+    parts.push("Scan baseline missing. Run `kaddo scan` for better context.\n");
+  }
+  parts.push("## Current Knowledge\n");
+  parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
+  parts.push("## Roadmap\n");
+  if (pack.roadmap.present) {
+    parts.push(
+      [
+        `- Roadmap candidates: ${pack.roadmap.candidates}`,
+        `- Materialized work items: ${pack.roadmap.materialized}`,
+        `- Remaining candidates: ${pack.roadmap.remaining}`
+      ].join("\n") + "\n"
     );
-    if (grouped.length > 0) {
-      lines.push("## Work Items by Initiative");
-      for (const g of grouped) {
-        const parts = LIFECYCLE_STATES.filter((s) => g.states[s] > 0).map(
-          (s) => `${LIFECYCLE_LABEL[s]}: ${g.states[s]}`
-        );
-        lines.push(`- ${g.name} \u2014 ${parts.join(" \xB7 ")}`);
-      }
-      lines.push("");
+    if (pack.roadmap.remaining > 0) {
+      parts.push(
+        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+      );
     }
   }
-  const active = exp.workItems.items.filter((i) => i.lifecycle === "in-progress");
-  if (active.length > 0) {
-    lines.push("## In Progress");
-    for (const wi of active) {
+  parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
+  parts.push("## Active Work Items\n");
+  if (knowledge.workItems.length > 0) {
+    const lines = knowledge.workItems.map((wi) => {
       const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
-      const owned = wi.hasOwnership ? " \u25CF" : " \u25CB";
-      lines.push(`-${owned} ${wi.id}${level} \u2014 ${wi.title}`);
-    }
-    lines.push("");
+      const status = wi.lifecycle ? ` (${wi.lifecycle})` : wi.status ? ` (${wi.status})` : "";
+      const domains = wi.domains.length > 0 ? ` \xB7 domains: ${wi.domains.join(", ")}` : "";
+      return `- ${wi.id || wi.title} [${wi.type}]${level}${status} \u2014 ${wi.title}${domains}`;
+    });
+    parts.push(lines.join("\n") + "\n");
+  } else {
+    parts.push("No active work items found.\n");
   }
-  if (exp.domains.length > 0) {
-    lines.push("## Domains");
-    lines.push(`- ${exp.domains.join(", ")}`);
-    lines.push("");
+  const mixEntries = Object.entries(pack.deliveryMix).sort((a, b) => b[1] - a[1]);
+  if (mixEntries.length > 0) {
+    parts.push("## Delivery Mix\n");
+    parts.push("Active Work Items by type:\n");
+    const label = (t) => {
+      const c = t.charAt(0).toUpperCase() + t.slice(1);
+      return c.endsWith("s") ? c : `${c}s`;
+    };
+    parts.push(mixEntries.map(([t, n]) => `- ${label(t)}: ${n}`).join("\n") + "\n");
   }
-  lines.push("## Mapped Modules");
-  if (exp.mappedModules.length > 0) {
-    for (const m of exp.mappedModules) {
-      const owner = m.owner ? ` \u2014 owner: ${m.owner}` : "";
-      lines.push(`- ${m.id} \u2014 ${m.type ?? "unknown"} \u2014 ${m.repoPath || "\u2014"}${owner}`);
-    }
-    lines.push("");
-    lines.push("## Module Artifact Coverage");
-    for (const m of exp.mappedModules) {
-      const present = presentArtifacts(m.artifacts);
-      lines.push(`- ${m.id}: ${present.length > 0 ? present.join(", ") : "none"}`);
-    }
-    lines.push("");
+  parts.push("## Artifacts and Ownership\n");
+  if (knowledge.artifacts.length > 0) {
+    const lines = knowledge.artifacts.map(
+      (a) => `- ${a.id || a.title} [${a.type}] owns: ${a.codeGlobs.join(", ")}`
+    );
+    parts.push(lines.join("\n") + "\n");
   } else {
-    lines.push("- Mapped modules: 0");
-    lines.push("");
-  }
-  if (exp.externalCapsules.length > 0) {
-    lines.push(`## External Knowledge Capsules: ${exp.externalCapsules.length}`);
-    for (const cap of exp.externalCapsules) {
-      const owner = cap.owner ? ` \u2014 owner: ${cap.owner}` : "";
-      lines.push(`- ${cap.system}${owner}`);
-      if (cap.ageDays !== null && cap.ageDays >= 90) {
-        lines.push(`  \u26A0 capsule last updated ${cap.ageDays} days ago \u2014 it may be stale.`);
-      }
-    }
-    lines.push("");
+    parts.push("No artifacts declare code ownership yet.\n");
   }
-  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 (pack.mappedModules.length > 0) {
+    parts.push("## Mapped Modules\n");
+    parts.push("This project has mapped modules registered in `.kaddo/modules.yml`.\n");
+    const header = "| Module | Type | Repo path | Owner | Capabilities | Artifacts |";
+    const sep = "|---|---|---|---|---|---|";
+    const rows = pack.mappedModules.map((m) => {
+      const caps = m.capabilities.length > 0 ? m.capabilities.join(", ") : "\u2014";
+      const arts = presentArtifacts(m.artifacts);
+      return `| ${m.id} | ${m.type ?? "\u2014"} | ${m.repoPath || "\u2014"} | ${m.owner ?? "\u2014"} | ${caps} | ${arts.length > 0 ? arts.join(", ") : "none"} |`;
+    });
+    parts.push([header, sep, ...rows].join("\n") + "\n");
+    parts.push(
+      "Note: Kaddo does not scan secondary repositories during `context`. Mapped modules come from `.kaddo/modules.yml` and module artifacts only.\n"
+    );
   }
-  if (exp.skills.total > 0) {
-    lines.push(`## Skills installed: ${exp.skills.total}`);
-    const groups = Object.entries(exp.skills.byGroup).sort((a, b) => a[0].localeCompare(b[0]));
-    if (groups.length > 0) {
-      lines.push("Groups:");
-      for (const [g, n] of groups) lines.push(`- ${g}: ${n}`);
+  if (pack.external.length > 0) {
+    parts.push("## External Knowledge\n");
+    parts.push(
+      "Imported Knowledge Capsules \u2014 minimal context about external systems (not their source).\n"
+    );
+    for (const cap of pack.external) {
+      const lines = [`### ${cap.system}`, ""];
+      if (cap.purpose) lines.push(`- Purpose: ${cap.purpose}`);
+      if (cap.capabilities.length) lines.push(`- Capabilities: ${cap.capabilities.join(", ")}`);
+      if (cap.contracts.length) lines.push(`- Contracts: ${cap.contracts.join(", ")}`);
+      if (cap.owner) lines.push(`- Owner: ${cap.owner}`);
+      if (cap.knownRisks.length) lines.push(`- Known risks: ${cap.knownRisks.join("; ")}`);
+      parts.push(lines.join("\n") + "\n");
     }
-    lines.push("");
   }
-  if (exp.missingKnowledge.length > 0) {
-    lines.push("## Missing Knowledge");
-    for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
-    lines.push("");
+  if (pack.graph) {
+    parts.push("## Knowledge Graph\n");
+    parts.push(
+      [
+        "- Available: yes",
+        `- Scope: ${pack.graph.scope}`,
+        `- Nodes: ${pack.graph.nodes}`,
+        `- Edges: ${pack.graph.edges}`,
+        ...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");
   }
-  if (exp.duplicateWorkItems.length > 0) {
-    lines.push("## Possible Duplicate Work Items");
-    for (const g of exp.duplicateWorkItems) {
-      lines.push(`- ${g.reason}:`);
-      for (const i of g.items) lines.push(`  - ${i.id} \u2014 ${i.title}`);
+  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\`)
+`);
     }
-    lines.push("Review before continuing (non-blocking).");
-    lines.push("");
   }
-  const assessment = assessPhase(exp);
-  lines.push("## Phase");
-  lines.push(`- Phase: ${assessment.phase}`);
-  if (assessment.reasons.length > 0) {
-    lines.push("- Reason:");
-    for (const r of assessment.reasons) lines.push(`  - ${r}`);
+  if (pack.skills.length > 0) {
+    parts.push("## Skills\n");
+    parts.push("Available reusable skills (agents apply these; content is not inlined):\n");
+    parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
+    parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
   }
-  if (assessment.nextStep) lines.push(`- Next step: ${assessment.nextStep}`);
-  lines.push("");
-  if (exp.suggestedNextSteps.length > 0) {
-    lines.push("## Suggested Next Steps");
-    exp.suggestedNextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
-    lines.push("");
+  parts.push("## Missing Context\n");
+  if (missing.length > 0) {
+    parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
+  } else {
+    parts.push("_None \u2014 all expected context is present._\n");
   }
-  return lines.join("\n").trimEnd() + "\n";
-}
-function renderExplanationAgent(exp) {
-  const { mappedModules, ...rest } = exp;
-  return JSON.stringify({ ...rest, mapped_modules: mappedModules }, null, 2) + "\n";
+  parts.push("## Recommended Agent Handoff\n");
+  parts.push(`Recommended next for the **${pack.phase.phase}** phase:
+`);
+  parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
+  if (handoff.nextSteps.length > 0) {
+    parts.push("Next step:\n");
+    parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
+  }
+  parts.push("## Instructions for the LLM\n");
+  parts.push(handoff.instructions.map((i) => `- ${i}`).join("\n") + "\n");
+  return parts.join("\n");
 }
 
 // ../cli/src/agents/groups.ts
@@ -3046,6 +3350,22 @@ function generateGraph(root, scope = "active") {
     next_suggested_resources: ["kaddo://graph", "kaddo://graph-hints"]
   };
 }
+function generateImpactReport(root, opts = {}) {
+  requireConfig(root);
+  requireKnowledge(root);
+  const format = opts.format ?? "markdown";
+  const report = buildImpactReport(root, { scope: opts.scope ?? "all" });
+  const content = format === "json" ? serializeImpactJson(report) : renderImpactMarkdown(report);
+  const out = opts.output ?? `.kaddo/reports/impact-report.${format === "json" ? "json" : "md"}`;
+  writeDerived(root, out, content);
+  return {
+    status: "ok",
+    files_written: [out.replace(/\\/g, "/")],
+    summary: `Impact report generated (${format}, ${report.scope} scope).`,
+    warnings: report.score === null ? ["Impact score not available \u2014 add Work Items to compute it."] : [],
+    next_suggested_resources: ["kaddo://impact-report"]
+  };
+}
 function generateCapsuleDraft(root) {
   const config = requireConfig(root);
   requireKnowledge(root);
@@ -3229,6 +3549,23 @@ function createServer(root) {
     },
     async (args) => generated(root, "generate knowledge graph", () => generateGraph(root, args.scope ?? "active"))
   );
+  server.registerTool(
+    "kaddo_generate_impact_report",
+    {
+      title: "Generate impact report",
+      description: `Write the Knowledge Impact Report under .kaddo/reports/. format: markdown (default) or json; scope: active or all (default all). ${DERIVED_NOTE}`,
+      inputSchema: {
+        format: z2.enum(["markdown", "json"]).optional(),
+        scope: z2.enum(["active", "all"]).optional(),
+        output: z2.string().optional()
+      }
+    },
+    async (args) => generated(
+      root,
+      "generate impact report",
+      () => generateImpactReport(root, { format: args.format, scope: args.scope, output: args.output })
+    )
+  );
   server.registerTool(
     "kaddo_generate_capsule_draft",
     { title: "Generate capsule draft", description: `Write a capsule DRAFT under .kaddo/exports/ (never registers it). ${DERIVED_NOTE}`, inputSchema: {} },