@kaddo/mcp 3.19.0 → 3.21.0

package/dist/index.js

@@ -4,8 +4,9 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
+import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/catalog.ts
 import matter from "gray-matter";
@@ -76,6 +77,39 @@ function readYaml(root, relPath) {
     return null;
   }
 }
+var DERIVED_WRITE_FILES = /* @__PURE__ */ new Set([
+  ".kaddo/context-pack.md",
+  ".kaddo/context-pack.json",
+  ".kaddo/explain.md",
+  ".kaddo/explain.json",
+  ".kaddo/understand.md",
+  ".kaddo/understand.json",
+  ".kaddo/graph.json",
+  ".kaddo/graph.mmd",
+  ".kaddo/graph-hints.md",
+  ".kaddo/graph-hints.json"
+]);
+var DERIVED_EXPORTS_RE = /^\.kaddo\/exports\/[^/]+\.capsule\.(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)) {
+    throw new KaddoMcpError("Blocked unsafe MCP derived write path.");
+  }
+  return p;
+}
+function writeDerived(root, relPath, content) {
+  const p = assertMcpDerivedWritePath(relPath);
+  const abs = path.resolve(root, p);
+  const base = toPosix(root).replace(/\/+$/, "");
+  if (toPosix(abs) !== base && !toPosix(abs).startsWith(base + "/")) {
+    throw new KaddoMcpError("Blocked unsafe MCP derived write path.");
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, "utf-8");
+}
 function listFiles(root, relDir, filterExt) {
   let absDir;
   try {
@@ -173,8 +207,50 @@ function getAgentPrompt(root, name) {
   return { ...info, content };
 }
 
-// src/workitems.ts
+// src/skills.ts
 import matter2 from "gray-matter";
+function firstHeadingOrLine2(md) {
+  for (const line of md.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#") || t.startsWith("---")) continue;
+    return t.replace(/\s+/g, " ").slice(0, 200);
+  }
+  return "";
+}
+function listSkills(root) {
+  const files = listFiles(root, "knowledge/skills", "skill.md");
+  const out = [];
+  for (const rel of files) {
+    const raw = readText(root, rel);
+    if (raw === null) continue;
+    let data = {};
+    try {
+      data = matter2(raw).data;
+    } catch {
+    }
+    if (data.type && String(data.type) !== "skill") continue;
+    const folder = rel.split("/").slice(-2)[0];
+    out.push({
+      id: String(data.id ?? folder),
+      title: String(data.title ?? folder),
+      group: String(data.group ?? "unknown"),
+      applies_to: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+      path: rel
+    });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function getSkill(root, id) {
+  const want = id.replace(/\.md$/, "");
+  const info = listSkills(root).find((s) => s.id === want);
+  if (!info) return null;
+  const content = readText(root, info.path);
+  if (content === null) return null;
+  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) : [];
@@ -201,7 +277,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter2(raw);
+      parsed = matter3(raw);
     } catch {
       continue;
     }
@@ -362,18 +438,15 @@ var RESOURCES = [
   {
     uri: "kaddo://skills",
     name: "Kaddo skills",
-    description: "Installed skills from knowledge/skills/ (empty if none).",
+    description: "Installed reusable skills from knowledge/skills/ (empty if none).",
     mimeType: "application/json",
-    read: (root) => {
-      const files = listFiles(root, "knowledge/skills", ".md");
-      return [
-        {
-          uri: "kaddo://skills",
-          text: JSON.stringify({ skills: files }, null, 2),
-          mimeType: "application/json"
-        }
-      ];
-    }
+    read: (root) => [
+      {
+        uri: "kaddo://skills",
+        text: JSON.stringify({ skills: listSkills(root) }, null, 2),
+        mimeType: "application/json"
+      }
+    ]
   }
 ];
 
@@ -465,6 +538,14 @@ function getAgentPromptTool(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.");
@@ -475,114 +556,2655 @@ function listGraphHints(root, filter = {}) {
   return ok({ quality: report.quality ?? "unknown", count: hints.length, hints });
 }
 
-// src/server.ts
-var SERVER_NAME = "kaddo";
-var SERVER_VERSION = "3.19.0";
-function toolText(result) {
-  if (!result.ok) {
-    return { content: [{ type: "text", text: result.message }], isError: true };
+// ../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";
+}
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
   }
-  const text2 = typeof result.data === "string" ? result.data : JSON.stringify(result.data, null, 2);
-  return { content: [{ type: "text", text: text2 }] };
+};
+var projectStateSchema = z.enum(["new", "pre-ai", "legacy"], {
+  errorMap: () => ({
+    message: `project.state must be one of: ${PROJECT_STATES.join(", ")}`
+  })
+});
+var teamSizeSchema = z.enum(["indie", "small", "medium", "enterprise"], {
+  errorMap: () => ({
+    message: `team.size must be one of: ${TEAM_SIZES.join(", ")}`
+  })
+});
+var structureSchema = z.enum(["monorepo", "multirepo"], {
+  errorMap: () => ({
+    message: `project.structure must be one of: ${REPOSITORY_STRUCTURES.join(", ")}`
+  })
+});
+var languageSchema = z.enum(["en", "es"], {
+  errorMap: () => ({
+    message: `project.language must be one of: ${PROJECT_LANGUAGES.join(", ")}`
+  })
+});
+var configSchema = z.object({
+  version: z.union([z.string(), z.number()]).optional(),
+  project: z.object({
+    name: z.string().default("project"),
+    state: projectStateSchema.default(DEFAULTS.state),
+    structure: structureSchema.default(DEFAULTS.structure),
+    language: languageSchema.default(DEFAULTS.language),
+    domains: z.array(z.string()).optional()
+  }).passthrough().default({}),
+  team: z.object({
+    size: teamSizeSchema.default(DEFAULTS.teamSize)
+  }).passthrough().default({}),
+  knowledge: z.unknown().optional(),
+  guard: z.unknown().optional(),
+  scan: z.unknown().optional()
+}).passthrough();
+function configPathFor(dir) {
+  return join(dir, ".kaddo", "config.yml");
 }
-function guarded(root, fn) {
+function loadConfig(dir) {
+  const configPath = configPathFor(dir);
+  if (!exists(configPath)) return null;
+  let raw;
   try {
-    assertKaddoProject(root);
-    return fn();
+    raw = parseYaml2(readFile(configPath));
   } catch (err) {
-    if (err instanceof KaddoMcpError) return { ok: false, message: err.message };
-    throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ConfigError(`Could not parse .kaddo/config.yml: ${detail}`);
+  }
+  const parsed = configSchema.safeParse(raw ?? {});
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => {
+      const path3 = i.path.join(".");
+      return path3 ? `  - ${path3}: ${i.message}` : `  - ${i.message}`;
+    }).join("\n");
+    throw new ConfigError(`Invalid .kaddo/config.yml:
+${issues}`);
   }
+  return parsed.data;
 }
-function createServer(root) {
-  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
-  for (const r of RESOURCES) {
-    server.registerResource(
-      r.name,
-      r.uri,
-      { title: r.name, description: r.description, mimeType: r.mimeType },
-      async (uri) => {
-        try {
-          assertKaddoProject(root);
-        } catch (err) {
-          const message = err instanceof KaddoMcpError ? err.message : String(err);
-          return { contents: [{ uri: uri.href, text: message, mimeType: "text/plain" }] };
-        }
-        const parts = r.read(root);
-        return { contents: parts.map((p) => ({ uri: p.uri, text: p.text, mimeType: p.mimeType })) };
-      }
-    );
+
+// ../cli/src/core/context-pack.ts
+import matter7 from "gray-matter";
+
+// ../cli/src/services/artifact-reader.ts
+import matter4 from "gray-matter";
+function parseArtifact(filePath, raw) {
+  try {
+    const { data } = matter4(raw);
+    const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
+    return {
+      filePath,
+      id: String(data.id ?? ""),
+      type: String(data.type ?? ""),
+      title: String(data.title ?? ""),
+      summary: String(data.summary ?? ""),
+      knowledgeLevel: String(data.knowledge_level ?? ""),
+      codeGlobs: globs,
+      domains: Array.isArray(data.domains) ? data.domains : [],
+      capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String).filter(Boolean) : [],
+      status: String(data.status ?? ""),
+      phase: String(data.phase ?? ""),
+      initiative: String(data.initiative ?? data.source_initiative ?? ""),
+      source: data.source ? String(data.source) : "",
+      sourceId: String(data.source_id ?? ""),
+      decisions: Array.isArray(data.decisions) ? data.decisions.map(String).filter(Boolean) : [],
+      capsules: Array.isArray(data.capsules) ? data.capsules.map(String).filter(Boolean) : []
+    };
+  } catch {
+    return null;
   }
-  server.registerTool(
-    "kaddo_project_status",
-    { title: "Kaddo project status", description: "Compact project status (state, phase, work items, ownership, graph quality, capsules).", inputSchema: {} },
-    async () => toolText(guarded(root, () => projectStatus(root)))
-  );
-  server.registerTool(
-    "kaddo_list_work_items",
-    {
-      title: "List Work Items",
-      description: "List Work Items with optional status/type/knowledge_level filters.",
-      inputSchema: {
-        status: z.string().optional(),
-        type: z.string().optional(),
-        knowledge_level: z.string().optional()
+}
+function readArtifacts(archDir) {
+  const artifacts = [];
+  function walkDir(dir) {
+    const entries = readDir(dir);
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      if (isFile(fullPath) && entry.endsWith(".md")) {
+        const raw = readFile(fullPath);
+        const artifact = parseArtifact(fullPath, raw);
+        if (artifact) artifacts.push(artifact);
+      } else if (!isFile(fullPath) && !entry.startsWith(".")) {
+        walkDir(fullPath);
       }
-    },
-    async (args) => toolText(guarded(root, () => listWorkItemsTool(root, args)))
-  );
-  server.registerTool(
-    "kaddo_get_work_item",
-    { title: "Get Work Item", description: "Get a Work Item by ID (summary + full markdown).", inputSchema: { id: z.string() } },
-    async (args) => toolText(guarded(root, () => getWorkItem(root, args.id)))
-  );
-  server.registerTool(
-    "kaddo_list_capsules",
-    { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },
-    async () => toolText(guarded(root, () => listCapsulesTool(root)))
-  );
-  server.registerTool(
-    "kaddo_get_capsule",
-    { title: "Get Knowledge Capsule", description: "Get an external Knowledge Capsule by ID.", inputSchema: { id: z.string() } },
-    async (args) => toolText(guarded(root, () => getCapsuleTool(root, args.id)))
-  );
-  server.registerTool(
-    "kaddo_list_agents",
-    { title: "List agents", description: "List installed agent prompts.", inputSchema: {} },
-    async () => toolText(guarded(root, () => listAgentsTool(root)))
-  );
-  server.registerTool(
-    "kaddo_get_agent_prompt",
-    { title: "Get agent prompt", description: "Get an installed agent prompt by name.", inputSchema: { name: z.string() } },
-    async (args) => toolText(guarded(root, () => getAgentPromptTool(root, args.name)))
-  );
-  server.registerTool(
-    "kaddo_list_graph_hints",
-    {
-      title: "List graph hints",
-      description: "List knowledge-graph relationship hints with optional filters.",
-      inputSchema: {
-        artifact_type: z.string().optional(),
-        severity: z.string().optional(),
-        active_only: z.boolean().optional()
+    }
+  }
+  walkDir(archDir);
+  return artifacts;
+}
+
+// ../cli/src/core/lifecycle.ts
+var LIFECYCLE_STATES = [
+  "draft",
+  "ready",
+  "in-progress",
+  "blocked",
+  "completed",
+  "archived"
+];
+var ACTIVE_STATES2 = ["draft", "ready", "in-progress", "blocked"];
+var LEGACY_STATUS_MAP = {
+  done: "completed",
+  cancelled: "archived",
+  canceled: "archived",
+  "in-progress": "in-progress"
+};
+var STATE_SET = new Set(LIFECYCLE_STATES);
+function isLifecycleState(s) {
+  return STATE_SET.has(s);
+}
+function isActiveState(s) {
+  return ACTIVE_STATES2.includes(s);
+}
+function lifecycleFolderOf(filePath) {
+  const p = filePath.replace(/\\/g, "/");
+  const m = p.match(/\/delivery\/work-items\/([^/]+)\//);
+  if (m && isLifecycleState(m[1])) return m[1];
+  return null;
+}
+function lifecycleStateOf(item) {
+  const status = (item.status ?? "").trim().toLowerCase();
+  if (isLifecycleState(status)) return status;
+  if (status && LEGACY_STATUS_MAP[status]) return LEGACY_STATUS_MAP[status];
+  const folder = lifecycleFolderOf(item.filePath ?? "");
+  if (folder) return folder;
+  return "ready";
+}
+function emptyLifecycleCounts() {
+  return Object.fromEntries(LIFECYCLE_STATES.map((s) => [s, 0]));
+}
+function lifecycleCounts(states) {
+  const counts = emptyLifecycleCounts();
+  for (const s of states) counts[s]++;
+  return counts;
+}
+
+// ../cli/src/services/knowledge-artifacts.ts
+var ARCH_DIR = "knowledge";
+function toPosix2(p) {
+  return p.replace(/\\/g, "/");
+}
+function relativeTo(dir, filePath) {
+  const base = toPosix2(dir).replace(/\/+$/, "");
+  const full = toPosix2(filePath);
+  return full.startsWith(base + "/") ? full.slice(base.length + 1) : full;
+}
+function isWorkItemArtifact(a) {
+  return toPosix2(a.filePath).includes("/delivery/work-items/") && Boolean(a.type);
+}
+function classifyLayer(posixPath) {
+  if (posixPath.includes("/knowledge/business/")) return "business";
+  if (posixPath.includes("/knowledge/product/")) return "product";
+  if (posixPath.includes("/knowledge/tech/modules/") || posixPath.includes("/knowledge/modules/"))
+    return "module";
+  if (posixPath.includes("/knowledge/tech/")) return "tech";
+  if (posixPath.includes("/knowledge/delivery/")) return "delivery";
+  return "unknown";
+}
+function enrich(dir, a) {
+  const posix = toPosix2(a.filePath);
+  const isWi = isWorkItemArtifact(a);
+  return {
+    ...a,
+    relPath: relativeTo(dir, a.filePath),
+    layer: classifyLayer(posix),
+    isWorkItem: isWi,
+    lifecycle: isWi ? lifecycleStateOf({ status: a.status, filePath: a.filePath }) : void 0
+  };
+}
+function discoverKnowledge(dir) {
+  const archDir = join(dir, ARCH_DIR);
+  if (!exists(archDir)) return [];
+  return readArtifacts(archDir).map((a) => enrich(dir, a));
+}
+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) : [];
+}
+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 loadMappedModules(dir) {
+  const path3 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path3)) return [];
+  let parsed;
+  try {
+    parsed = parseYaml3(readFile(path3));
+  } catch {
+    return [];
+  }
+  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 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;
+}
+
+// ../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;
       }
-    },
-    async (args) => toolText(guarded(root, () => listGraphHints(root, args)))
-  );
-  let prompts = [];
+      continue;
+    }
+    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, 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()
+  };
+}
+function existsDirWithMd(d) {
+  if (!exists(d)) return false;
   try {
-    assertKaddoProject(root);
-    prompts = listPrompts(root);
+    return readDir(d).some((e) => e.endsWith(".md") && isFile(join(d, e)));
   } catch {
-    prompts = [];
+    return false;
   }
-  for (const p of prompts) {
-    server.registerPrompt(
-      p.name,
-      { title: p.name, description: p.description },
-      async () => {
-        const full = getPrompt(root, p.name);
-        const content = full?.content ?? `Agent "${p.name}" is not installed.`;
+}
+function statusFor(layer2, a) {
+  if (layer2 === "Delivery") {
+    if (a.hasWorkItem) return "Traceable";
+    if (a.hasRoadmap) return "Partial";
+    return "Missing";
+  }
+  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("");
+  }
+  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);
+  }
+  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;
+    }
+  };
+  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 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()
+    });
+  };
+  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;
+    }
+  }
+  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/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 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 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(", "));
+  }
+  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;
+    }
+    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."
+        ];
+      }
+      if (input.ownership.workItemsMissingOwnership > 0) {
+        recommendedAgents.push("kaddo owners suggest");
+        llmInstructions.push("Ownership is incomplete \u2014 propose `code:` globs (run `kaddo owners suggest`).");
+      }
+      break;
+    }
+    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;
+    }
+  }
+  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)];
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+// ../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 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 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;
+  }
+  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));
+  }
+  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
+  };
+}
+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;
+}
+
+// ../cli/src/core/graph.ts
+var KNOWLEDGE3 = "knowledge";
+function toPosix3(p) {
+  return p.replace(/\\/g, "/");
+}
+function slug(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 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 selectedWIs = scope === "active" ? workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)) : workItems;
+  for (const wi of selectedWIs) {
+    const id = wi.id || wi.title;
+    const wiNodeId = `wi:${id}`;
+    addNode({
+      id: wiNodeId,
+      type: "work-item",
+      label: `${id} ${wi.title}`.trim(),
+      path: wi.relPath,
+      status: wi.lifecycle,
+      knowledge_level: wi.knowledgeLevel || void 0
+    });
+    for (const glob of wi.codeGlobs) {
+      const codeId = `code:${glob}`;
+      addNode({ id: codeId, type: "code-glob", label: glob });
+      addEdge(wiNodeId, codeId, "owns");
+    }
+    for (const cap of wi.capabilities) {
+      const capId = `capability:${slug(cap) || cap}`;
+      addNode({ id: capId, type: "capability", label: cap });
+      addEdge(wiNodeId, capId, "implements");
+    }
+    for (const dec of wi.decisions) {
+      const adrId = `adr:${dec}`;
+      addNode({ id: adrId, type: "decision", label: dec });
+      addEdge(wiNodeId, adrId, "depends_on");
+    }
+    if (wi.initiative) {
+      const initId = `initiative:${slug(wi.initiative) || wi.initiative}`;
+      addNode({ id: initId, type: "initiative", label: wi.initiative });
+      addEdge(wiNodeId, initId, "belongs_to");
+    }
+    if (wi.source === "roadmap" && wi.sourceId) {
+      const candId = `candidate:${wi.sourceId}`;
+      addNode({ id: candId, type: "roadmap-candidate", label: wi.sourceId });
+      addEdge(candId, wiNodeId, "materialized_as");
+    }
+  }
+  for (const adr of all.filter(isAdr)) {
+    const adrId = `adr:${adr.id || adr.title}`;
+    const referenced = nodes.has(adrId);
+    if (scope === "all" || referenced) {
+      nodes.set(adrId, {
+        id: adrId,
+        type: "decision",
+        label: `${adr.id} ${adr.title}`.trim() || adr.id || adr.title,
+        path: adr.relPath
+      });
+      for (const glob of adr.codeGlobs) {
+        const codeId = `code:${glob}`;
+        addNode({ id: codeId, type: "code-glob", label: glob });
+        addEdge(adrId, codeId, "governs");
+      }
+    }
+  }
+  const capsules = loadExternalRegistry(dir);
+  if (capsules.length > 0) {
+    const projId = `project:${slug(config.project.name) || "project"}`;
+    addNode({ id: projId, type: "project", label: config.project.name });
+    for (const cap of capsules) {
+      const capId = `capsule:${cap.id}`;
+      addNode({ id: capId, type: "knowledge-capsule", label: cap.id, path: cap.path });
+      addEdge(capId, projId, "provides_external_context");
+      for (const wi of selectedWIs) {
+        if (wi.capsules.includes(cap.id)) {
+          addEdge(`wi:${wi.id || wi.title}`, capId, "uses_external_knowledge");
+        }
+      }
+    }
+  }
+  return {
+    generated_at: now.toISOString(),
+    project: {
+      name: config.project.name,
+      state: config.project.state,
+      structure: config.project.structure
+    },
+    nodes: [...nodes.values()],
+    edges
+  };
+}
+function serializeGraphJson(graph) {
+  return JSON.stringify(graph, null, 2) + "\n";
+}
+function renderGraphMermaid(graph) {
+  const safeIds = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  const safe = (id) => {
+    const existing = safeIds.get(id);
+    if (existing) return existing;
+    let base = id.replace(/[^a-zA-Z0-9]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+    if (!base) base = "n";
+    let candidate = base;
+    let i = 1;
+    while (used.has(candidate)) candidate = `${base}_${i++}`;
+    used.add(candidate);
+    safeIds.set(id, candidate);
+    return candidate;
+  };
+  const escapeLabel = (s) => s.replace(/"/g, "'");
+  const lines = ["flowchart LR"];
+  for (const node of graph.nodes) {
+    lines.push(`  ${safe(node.id)}["${escapeLabel(node.label)}"]`);
+  }
+  if (graph.edges.length > 0) lines.push("");
+  for (const edge of graph.edges) {
+    lines.push(`  ${safe(edge.from)} -->|${edge.type}| ${safe(edge.to)}`);
+  }
+  return lines.join("\n") + "\n";
+}
+var ACTIVE_WI_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
+function loadGraphSummary(dir) {
+  const 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)
+    );
+    return {
+      generatedAt: String(graph.generated_at ?? ""),
+      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 buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
+  const artifacts = discoverKnowledge(dir);
+  const workItems = artifacts.filter((a) => a.isWorkItem);
+  const activeWIs = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle));
+  const adrs = artifacts.filter(isAdr2);
+  const capsules = loadExternalRegistry(dir);
+  const hints = [];
+  const referencedCapabilitySlugs = new Set(
+    workItems.flatMap((w) => w.capabilities.map((c) => slug2(c)))
+  );
+  const referencedCapsuleIds = new Set(workItems.flatMap((w) => w.capsules.map((c) => c)));
+  let activeWithoutCode = 0;
+  let activeWithoutCapabilities = 0;
+  let wisWithoutSource = 0;
+  for (const wi of activeWIs) {
+    const id = wi.id || wi.title;
+    const missing = [];
+    const suggested = {};
+    if (wi.codeGlobs.length === 0) {
+      missing.push("code");
+      suggested.code = ["src/<area>/**"];
+      activeWithoutCode++;
+    }
+    if (wi.capabilities.length === 0) {
+      missing.push("capabilities");
+      suggested.capabilities = ["<capability>"];
+      activeWithoutCapabilities++;
+    }
+    if (wi.decisions.length === 0) {
+      missing.push("decisions");
+      suggested.decisions = ["ADR-XXX"];
+    }
+    const hasSource = Boolean(wi.sourceId) || Boolean(wi.initiative);
+    if (!hasSource) {
+      missing.push("source");
+      wisWithoutSource++;
+    }
+    if (missing.length === 0) continue;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "work-item",
+      path: wi.relPath,
+      severity: "info",
+      missing,
+      reason: "Active Work Item has limited graph relationships.",
+      message: `${id} has no ${missing.map(humanMissing).join(", ")}.`,
+      suggested_front_matter: Object.keys(suggested).length > 0 ? suggested : void 0
+    });
+  }
+  let adrsWithoutCode = 0;
+  for (const adr of adrs) {
+    if (adr.codeGlobs.length > 0) continue;
+    adrsWithoutCode++;
+    const id = adr.id || adr.title;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "decision",
+      path: adr.relPath,
+      severity: "info",
+      missing: ["code"],
+      reason: "This ADR defines technical decisions but does not declare which paths it governs.",
+      message: `${id} has no governed code paths.`,
+      suggested_front_matter: { code: ["<path/to/code>"] }
+    });
+  }
+  for (const cap of capabilityHeadings(dir)) {
+    if (referencedCapabilitySlugs.has(slug2(cap))) continue;
+    hints.push({
+      artifact_id: cap,
+      artifact_type: "capability",
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This capability is declared but no Work Item references it yet.",
+      message: `Capability "${cap}" is not linked to any Work Item.`
+    });
+  }
+  let capsulesWithoutWi = 0;
+  for (const cap of capsules) {
+    if (referencedCapsuleIds.has(cap.id)) continue;
+    capsulesWithoutWi++;
+    hints.push({
+      artifact_id: cap.id,
+      artifact_type: "knowledge-capsule",
+      path: cap.path,
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This Knowledge Capsule is available but no Work Item declares `capsules:` for it.",
+      message: `Knowledge Capsule "${cap.id}" is not linked to any Work Item.`
+    });
+  }
+  const inEdge = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    inEdge.add(e.from);
+    inEdge.add(e.to);
+  }
+  const nodes = graph.nodes.length;
+  const connected = graph.nodes.filter((n) => inEdge.has(n.id)).length;
+  const relationshipEdges = graph.edges.filter((e) => e.type !== "informs").length;
+  const metrics = {
+    nodes_count: nodes,
+    edges_count: graph.edges.length,
+    connected_nodes_count: connected,
+    isolated_nodes_count: nodes - connected,
+    active_work_items_without_code: activeWithoutCode,
+    active_work_items_without_capabilities: activeWithoutCapabilities,
+    work_items_without_source: wisWithoutSource,
+    adrs_without_code: adrsWithoutCode,
+    capsules_without_related_work_items: capsulesWithoutWi
+  };
+  const quality = assessQuality(nodes, relationshipEdges, hints.length);
+  return {
+    generated_at: now.toISOString(),
+    quality,
+    summary: { nodes, edges: graph.edges.length, hints: hints.length },
+    metrics,
+    hints
+  };
+}
+function assessQuality(nodes, relationshipEdges, hintCount) {
+  if (nodes === 0 || relationshipEdges === 0) return "empty";
+  if (relationshipEdges / nodes < 0.25) return "sparse";
+  if (hintCount > 0) return "partial";
+  return "good";
+}
+var QUALITY_NOTE = {
+  good: "Most active artifacts have meaningful relationships.",
+  partial: "Some active artifacts have missing relationship metadata.",
+  sparse: "The graph has many nodes but few meaningful edges.",
+  empty: "The graph has almost no relationships."
+};
+function yamlBlock(fm) {
+  const lines = ["```yaml"];
+  for (const [k, vals] of Object.entries(fm)) {
+    lines.push(`${k}:`);
+    for (const v of vals) lines.push(`  - ${v}`);
+  }
+  lines.push("```");
+  return lines;
+}
+function renderGraphHintsMarkdown(report) {
+  const lines = [];
+  lines.push("# Kaddo Graph Hints");
+  lines.push("");
+  lines.push("Generated by `kaddo graph export`. Suggestions only \u2014 Kaddo never edits your artifacts.");
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- Relationship quality: ${report.quality} \u2014 ${QUALITY_NOTE[report.quality]}`);
+  lines.push(`- Nodes: ${report.summary.nodes}`);
+  lines.push(`- Edges: ${report.summary.edges}`);
+  lines.push(`- Hints: ${report.summary.hints}`);
+  lines.push("");
+  if (report.hints.length === 0) {
+    lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    lines.push("");
+    return lines.join("\n");
+  }
+  lines.push("## Hints");
+  lines.push("");
+  for (const h of report.hints) {
+    lines.push(`### ${h.artifact_id}${h.path ? ` \u2014 \`${h.path}\`` : ""}`);
+    lines.push("");
+    lines.push("Missing metadata:");
+    lines.push("");
+    for (const m of h.missing) lines.push(`- \`${m}\``);
+    lines.push("");
+    if (h.suggested_front_matter) {
+      lines.push("Suggested front matter:");
+      lines.push("");
+      lines.push(...yamlBlock(h.suggested_front_matter));
+      lines.push("");
+    }
+    lines.push(`Reason: ${h.reason}`);
+    lines.push("");
+  }
+  lines.push("> Use the `graph-agent` to turn these hints into precise front matter \u2014 you confirm and apply.");
+  lines.push("");
+  return lines.join("\n");
+}
+function serializeGraphHintsJson(report) {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+function loadGraphHints(dir) {
+  const p = join(dir, ".kaddo", "graph-hints.json");
+  if (!exists(p)) return null;
+  try {
+    const report = JSON.parse(readFile(p));
+    const hints = Array.isArray(report.hints) ? report.hints : [];
+    return {
+      quality: report.quality ?? "empty",
+      totalHints: hints.length,
+      activeWorkItemHints: hints.filter((h) => h.artifact_type === "work-item").length,
+      messages: hints.map((h) => h.message).filter(Boolean)
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ../cli/src/services/installed-skills.ts
+import matter6 from "gray-matter";
+var SKILLS_DIR = join("knowledge", "skills");
+function discoverInstalledSkills(dir) {
+  const base = join(dir, SKILLS_DIR);
+  if (!exists(base) || !isDir(base)) return [];
+  const out = [];
+  for (const entry of readDir(base)) {
+    const skillFile = join(base, entry, "skill.md");
+    if (!isFile(skillFile)) continue;
+    try {
+      const { data } = matter6(readFile(skillFile));
+      if (data.type && String(data.type) !== "skill") continue;
+      const id = String(data.id ?? entry);
+      out.push({
+        id,
+        title: String(data.title ?? id),
+        group: String(data.group ?? "unknown"),
+        appliesTo: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+        relPath: `${SKILLS_DIR.replace(/\\/g, "/")}/${entry}/skill.md`
+      });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function skillGroupCounts(skills) {
+  const counts = {};
+  for (const s of skills) counts[s.group] = (counts[s.group] ?? 0) + 1;
+  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;
+  }
+}
+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 readMarkdownSummary(dir, file) {
+  const p = join(dir, ARCH_DIR2, file);
+  if (!exists(p)) return null;
+  try {
+    return firstParagraph3(readFile(p));
+  } catch {
+    return null;
+  }
+}
+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"];
+  }
+}
+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."
+      ];
+  }
+}
+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.");
+  }
+  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
+    }
+  });
+  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
+    }
+  };
+}
+function serializeContextPackJson(pack) {
+  return JSON.stringify(pack, null, 2) + "\n";
+}
+
+// ../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");
+  }
+  if (pack.phase.recommendedAgents.length > 0) {
+    parts.push(`Recommended next: ${pack.phase.recommendedAgents.join(", ")}
+`);
+  }
+  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"
+  );
+  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 (scan.migrationDirectories.length > 0) {
+      lines.push("- Migration directories:");
+      scan.migrationDirectories.forEach((d) => lines.push(`  - ${d}`));
+    }
+    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 (pack.roadmap.remaining > 0) {
+      parts.push(
+        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+      );
+    }
+  }
+  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}`;
+    });
+    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");
+  }
+  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");
+  }
+  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 (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");
+    }
+  }
+  if (pack.graph) {
+    parts.push("## Knowledge Graph\n");
+    parts.push(
+      [
+        "- Available: yes",
+        `- Nodes: ${pack.graph.nodes}`,
+        `- Edges: ${pack.graph.edges}`,
+        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`
+      ].join("\n") + "\n"
+    );
+    parts.push("Full graph: `.kaddo/graph.json` / `.kaddo/graph.mmd` (run `kaddo graph export` to refresh).\n");
+  }
+  if (pack.graphHints && pack.graphHints.totalHints > 0) {
+    parts.push("## Graph Hints\n");
+    parts.push(
+      [
+        `Graph relationship quality: ${pack.graphHints.quality}`,
+        `Active hints: ${pack.graphHints.activeWorkItemHints}`,
+        "Suggested agent: graph-agent"
+      ].join("\n") + "\n"
+    );
+    const shown = pack.graphHints.messages.slice(0, 3);
+    parts.push(shown.map((m) => `- ${m}`).join("\n") + "\n");
+    if (pack.graphHints.totalHints > shown.length) {
+      parts.push(`(+${pack.graphHints.totalHints - shown.length} more in \`.kaddo/graph-hints.md\`)
+`);
+    }
+  }
+  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");
+  }
+  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/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 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 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 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;
+  }
+}
+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;
+  }
+  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;
+  }
+  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]++;
+  }
+  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.");
+  }
+  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(`- Nodes: ${exp.graph.nodes}`);
+    lines.push(`- Edges: ${exp.graph.edges}`);
+    if (exp.graphHints) {
+      lines.push(`- Quality: ${exp.graphHints.quality}`);
+      lines.push(`- Hints: ${exp.graphHints.totalHints}`);
+    }
+    if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
+    lines.push("");
+  }
+  if (exp.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/agents/groups.ts
+var AGENT_GROUPS = {
+  business: ["business-agent.md"],
+  product: ["bootstrap-agent.md", "capability-agent.md"],
+  tech: [
+    "architecture-agent.md",
+    "codebase-agent.md",
+    "stack-agent.md",
+    "security-agent.md",
+    "standards-agent.md",
+    "module-design-agent.md",
+    "adr-agent.md",
+    "capsule-agent.md",
+    "graph-agent.md"
+  ],
+  delivery: [
+    "backlog-agent.md",
+    "roadmap-agent.md",
+    "work-item-agent.md",
+    "implementation-agent.md",
+    "ownership-agent.md",
+    "git-strategy-agent.md"
+  ],
+  utilities: ["legacy-agent.md"]
+};
+var AGENT_GROUP_NAMES = Object.keys(AGENT_GROUPS);
+function agentGroupOf(fileName) {
+  for (const g of AGENT_GROUP_NAMES) {
+    if (AGENT_GROUPS[g].includes(fileName)) return g;
+  }
+  return "utilities";
+}
+function agentInstallPath(fileName) {
+  return `knowledge/agents/${agentGroupOf(fileName)}/${fileName}`;
+}
+
+// ../cli/src/core/understand.ts
+function agentIsInstalled(dir, fileName) {
+  return exists(join(dir, agentInstallPath(fileName))) || exists(join(dir, "knowledge", "agents", fileName));
+}
+function flowForState(state) {
+  switch (state) {
+    case "new":
+      return [
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" }
+      ];
+    case "legacy":
+      return [
+        { agent: "legacy-agent.md", output: "knowledge/legacy/risks.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" },
+        { agent: "capability-agent.md", output: "knowledge/product/capabilities.md" },
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" }
+      ];
+    case "pre-ai":
+    default:
+      return [
+        { agent: "capability-agent.md", output: "knowledge/product/capabilities.md" },
+        { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" },
+        { agent: "roadmap-agent.md", output: "knowledge/delivery/roadmap.md" }
+      ];
+  }
+}
+function buildUnderstandPlan(dir, config) {
+  const state = config.project.state;
+  const flow = flowForState(state).filter((s) => !exists(join(dir, s.output)));
+  const steps = flow.map((s) => {
+    const installed = agentIsInstalled(dir, s.agent);
+    return { agent: s.agent, output: s.output, installed };
+  });
+  const missingAgents = steps.filter((s) => !s.installed).map((s) => s.agent);
+  const agentsInstalled = exists(join(dir, "knowledge", "agents")) && missingAgents.length === 0;
+  return {
+    project: {
+      name: config.project.name,
+      state,
+      teamSize: config.team.size,
+      structure: config.project.structure
+    },
+    scanAvailable: exists(join(dir, ".kaddo", "scan.json")),
+    contextPackPath: ".kaddo/context-pack.md",
+    agentsInstalled,
+    missingAgents,
+    steps
+  };
+}
+
+// ../cli/src/templates/understand-template.ts
+function stateLabel2(state) {
+  return state === "pre-ai" ? "pre-AI" : state;
+}
+function agentName(file) {
+  return file.replace(/\.md$/, "");
+}
+function renderUnderstand(plan) {
+  const { project, steps } = plan;
+  const parts = [];
+  parts.push("# Kaddo Understand Handoff\n");
+  parts.push(
+    "> Generated by `kaddo understand`. Kaddo does not call an LLM \u2014 you stay in control of the interpretation.\n"
+  );
+  parts.push("## Project\n");
+  parts.push(
+    [
+      `- Name: ${project.name}`,
+      `- State: ${project.state}`,
+      `- Team: ${project.teamSize}`,
+      `- Structure: ${project.structure}`
+    ].join("\n") + "\n"
+  );
+  parts.push("## Recommended Agent Flow\n");
+  parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
+`);
+  parts.push(
+    steps.map((s, i) => {
+      const flag = s.installed ? "" : "  _(not installed \u2014 run `kaddo add agents`)_";
+      return `${i + 1}. ${agentName(s.agent)} \u2192 \`${s.output}\`${flag}`;
+    }).join("\n") + "\n"
+  );
+  parts.push("## Context Pack\n");
+  const scanNote = plan.scanAvailable ? "" : " (incomplete \u2014 run `kaddo scan` first for a richer baseline)";
+  parts.push(`Use \`${plan.contextPackPath}\` as the primary input${scanNote}.
+`);
+  parts.push("## Agent Prompts\n");
+  parts.push(
+    steps.map((s) => `- \`${agentInstallPath(s.agent)}\``).join("\n") + "\n"
+  );
+  parts.push("## Expected Outputs\n");
+  parts.push(steps.map((s) => `- \`${s.output}\``).join("\n") + "\n");
+  parts.push("## Copy/Paste Instructions\n");
+  const first2 = steps[0];
+  if (first2) {
+    parts.push(
+      [
+        `Start with **${agentName(first2.agent)}**:`,
+        "",
+        "1. Open your preferred LLM chat (Claude, ChatGPT, Cursor, Copilot, Windsurf\u2026).",
+        `2. Paste the context pack: \`${plan.contextPackPath}\``,
+        `3. Paste the agent prompt: \`${agentInstallPath(first2.agent)}\``,
+        `4. Ask the LLM to produce: \`${first2.output}\``,
+        `5. Save the result in: \`${first2.output}\``
+      ].join("\n") + "\n"
+    );
+  }
+  parts.push("## Next Steps\n");
+  if (steps.length > 1) {
+    parts.push(
+      `After saving \`${steps[0].output}\`, continue with **${agentName(steps[1].agent)}** (feed it the context pack plus the artifacts you already produced). Re-run \`kaddo understand\` any time to see this plan again.
+`
+    );
+  } else {
+    parts.push("Re-run `kaddo understand` any time to see this plan again.\n");
+  }
+  return parts.join("\n");
+}
+
+// src/generate.ts
+function requireConfig(root) {
+  const config = loadConfig(root);
+  if (!config) throw new KaddoMcpError("Kaddo project not found. Run `kaddo init` first.");
+  return config;
+}
+function requireKnowledge(root) {
+  if (!hasKnowledge(root)) {
+    throw new KaddoMcpError("Knowledge repository not found. Run `kaddo bootstrap` first.");
+  }
+}
+function slug3(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+function generateContext(root) {
+  const config = requireConfig(root);
+  requireKnowledge(root);
+  const pack = buildContextPack(root, config);
+  writeDerived(root, ".kaddo/context-pack.md", renderContextPack(pack));
+  writeDerived(root, ".kaddo/context-pack.json", serializeContextPackJson(pack));
+  return {
+    status: "ok",
+    files_written: [".kaddo/context-pack.md", ".kaddo/context-pack.json"],
+    summary: "Context pack generated successfully.",
+    warnings: pack.missing ?? [],
+    next_suggested_resources: ["kaddo://context-pack"]
+  };
+}
+function generateExplain(root) {
+  requireConfig(root);
+  requireKnowledge(root);
+  const exp = buildProjectExplanation(root);
+  writeDerived(root, ".kaddo/explain.md", renderExplanationHuman(exp));
+  writeDerived(root, ".kaddo/explain.json", renderExplanationAgent(exp));
+  return {
+    status: "ok",
+    files_written: [".kaddo/explain.md", ".kaddo/explain.json"],
+    summary: "Explain output generated successfully.",
+    warnings: exp.missingKnowledge ?? [],
+    next_suggested_resources: ["kaddo://explain"]
+  };
+}
+function generateUnderstand(root) {
+  const config = requireConfig(root);
+  requireKnowledge(root);
+  const plan = buildUnderstandPlan(root, config);
+  writeDerived(root, ".kaddo/understand.md", renderUnderstand(plan));
+  return {
+    status: "ok",
+    files_written: [".kaddo/understand.md"],
+    summary: "Understand guide generated successfully.",
+    warnings: [],
+    next_suggested_resources: ["kaddo://understand"]
+  };
+}
+function generateGraph(root) {
+  const config = requireConfig(root);
+  requireKnowledge(root);
+  const graph = buildGraph(root, config, { scope: "active" });
+  const hints = buildGraphHints(root, graph);
+  writeDerived(root, ".kaddo/graph.json", serializeGraphJson(graph));
+  writeDerived(root, ".kaddo/graph.mmd", renderGraphMermaid(graph));
+  writeDerived(root, ".kaddo/graph-hints.md", renderGraphHintsMarkdown(hints));
+  writeDerived(root, ".kaddo/graph-hints.json", serializeGraphHintsJson(hints));
+  const warnings = hints.summary.hints > 0 ? [`Relationship quality: ${hints.quality} \u2014 ${hints.summary.hints} metadata hint(s).`] : [];
+  return {
+    status: "ok",
+    files_written: [
+      ".kaddo/graph.json",
+      ".kaddo/graph.mmd",
+      ".kaddo/graph-hints.md",
+      ".kaddo/graph-hints.json"
+    ],
+    summary: "Knowledge graph and hints generated successfully.",
+    warnings,
+    next_suggested_resources: ["kaddo://graph", "kaddo://graph-hints"]
+  };
+}
+function generateCapsuleDraft(root) {
+  const config = requireConfig(root);
+  requireKnowledge(root);
+  const capsule = buildCapsule(root, config);
+  const name = slug3(config.project.name);
+  const md = `.kaddo/exports/${name}.capsule.md`;
+  const json = `.kaddo/exports/${name}.capsule.json`;
+  writeDerived(root, md, renderCapsuleMarkdown(capsule));
+  writeDerived(root, json, serializeCapsuleJson(capsule));
+  return {
+    status: "ok",
+    files_written: [md, json],
+    summary: `Capsule draft generated at ${md}. It is NOT registered as external context.`,
+    warnings: [
+      "Review the draft for secrets/source before sharing.",
+      "This draft is not imported anywhere. Use the CLI `kaddo capsule add` to register an external capsule."
+    ],
+    next_suggested_resources: []
+  };
+}
+
+// src/server.ts
+var SERVER_NAME = "kaddo";
+var require2 = createRequire(import.meta.url);
+var SERVER_VERSION = require2("../package.json").version;
+function toolText(result) {
+  if (!result.ok) {
+    return { content: [{ type: "text", text: result.message }], isError: true };
+  }
+  const text2 = typeof result.data === "string" ? result.data : JSON.stringify(result.data, null, 2);
+  return { content: [{ type: "text", text: text2 }] };
+}
+function guarded(root, fn) {
+  try {
+    assertKaddoProject(root);
+    return fn();
+  } catch (err) {
+    if (err instanceof KaddoMcpError) return { ok: false, message: err.message };
+    throw err;
+  }
+}
+function generated(root, label, fn) {
+  try {
+    assertKaddoProject(root);
+    const result = fn();
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    const message = err instanceof KaddoMcpError ? err.message : `Could not ${label}. ${String(err)}`;
+    return { content: [{ type: "text", text: message }], isError: true };
+  }
+}
+var DERIVED_NOTE = "Writes only derived files under .kaddo/. Does not modify knowledge, source code, external context or git.";
+function createServer(root) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  for (const r of RESOURCES) {
+    server.registerResource(
+      r.name,
+      r.uri,
+      { title: r.name, description: r.description, mimeType: r.mimeType },
+      async (uri) => {
+        try {
+          assertKaddoProject(root);
+        } catch (err) {
+          const message = err instanceof KaddoMcpError ? err.message : String(err);
+          return { contents: [{ uri: uri.href, text: message, mimeType: "text/plain" }] };
+        }
+        const parts = r.read(root);
+        return { contents: parts.map((p) => ({ uri: p.uri, text: p.text, mimeType: p.mimeType })) };
+      }
+    );
+  }
+  server.registerTool(
+    "kaddo_project_status",
+    { title: "Kaddo project status", description: "Compact project status (state, phase, work items, ownership, graph quality, capsules).", inputSchema: {} },
+    async () => toolText(guarded(root, () => projectStatus(root)))
+  );
+  server.registerTool(
+    "kaddo_list_work_items",
+    {
+      title: "List Work Items",
+      description: "List Work Items with optional status/type/knowledge_level filters.",
+      inputSchema: {
+        status: z2.string().optional(),
+        type: z2.string().optional(),
+        knowledge_level: z2.string().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => listWorkItemsTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_get_work_item",
+    { title: "Get Work Item", description: "Get a Work Item by ID (summary + full markdown).", inputSchema: { id: z2.string() } },
+    async (args) => toolText(guarded(root, () => getWorkItem(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_list_capsules",
+    { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listCapsulesTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_capsule",
+    { title: "Get Knowledge Capsule", description: "Get an external Knowledge Capsule by ID.", inputSchema: { id: z2.string() } },
+    async (args) => toolText(guarded(root, () => getCapsuleTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_list_agents",
+    { title: "List agents", description: "List installed agent prompts.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listAgentsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_agent_prompt",
+    { title: "Get agent prompt", description: "Get an installed agent prompt by name.", inputSchema: { name: z2.string() } },
+    async (args) => toolText(guarded(root, () => getAgentPromptTool(root, args.name)))
+  );
+  server.registerTool(
+    "kaddo_list_graph_hints",
+    {
+      title: "List graph hints",
+      description: "List knowledge-graph relationship hints with optional filters.",
+      inputSchema: {
+        artifact_type: z2.string().optional(),
+        severity: z2.string().optional(),
+        active_only: z2.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => listGraphHints(root, args)))
+  );
+  server.registerTool(
+    "kaddo_list_skills",
+    { title: "List skills", description: "List installed reusable skills.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listSkillsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_skill",
+    { title: "Get skill", description: "Get an installed reusable skill by id.", inputSchema: { id: z2.string() } },
+    async (args) => toolText(guarded(root, () => getSkillTool(root, args.id)))
+  );
+  let installedSkills = [];
+  try {
+    assertKaddoProject(root);
+    installedSkills = listSkills(root);
+  } catch {
+    installedSkills = [];
+  }
+  for (const s of installedSkills) {
+    server.registerResource(
+      `skill: ${s.id}`,
+      `kaddo://skills/${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).`, mimeType: "text/markdown" },
+      async (uri) => {
+        const full = getSkill(root, s.id);
+        return {
+          contents: [
+            { uri: uri.href, text: full?.content ?? `Skill "${s.id}" not found.`, mimeType: "text/markdown" }
+          ]
+        };
+      }
+    );
+  }
+  server.registerTool(
+    "kaddo_generate_context",
+    { title: "Generate context pack", description: `Regenerate .kaddo/context-pack.md + .json. ${DERIVED_NOTE}`, inputSchema: {} },
+    async () => generated(root, "generate context pack", () => generateContext(root))
+  );
+  server.registerTool(
+    "kaddo_generate_explain",
+    { title: "Generate explain", description: `Regenerate .kaddo/explain.md + .json. ${DERIVED_NOTE}`, inputSchema: {} },
+    async () => generated(root, "generate explain", () => generateExplain(root))
+  );
+  server.registerTool(
+    "kaddo_generate_understand",
+    { title: "Generate understand", description: `Regenerate .kaddo/understand.md. ${DERIVED_NOTE}`, inputSchema: {} },
+    async () => generated(root, "generate understand", () => generateUnderstand(root))
+  );
+  server.registerTool(
+    "kaddo_generate_graph",
+    { title: "Generate knowledge graph", description: `Regenerate .kaddo/graph.json/.mmd + graph-hints.md/.json. ${DERIVED_NOTE}`, inputSchema: {} },
+    async () => generated(root, "generate knowledge graph", () => generateGraph(root))
+  );
+  server.registerTool(
+    "kaddo_generate_capsule_draft",
+    { title: "Generate capsule draft", description: `Write a capsule DRAFT under .kaddo/exports/ (never registers it). ${DERIVED_NOTE}`, inputSchema: {} },
+    async () => generated(root, "generate capsule draft", () => generateCapsuleDraft(root))
+  );
+  let prompts = [];
+  try {
+    assertKaddoProject(root);
+    prompts = listPrompts(root);
+  } catch {
+    prompts = [];
+  }
+  for (const p of prompts) {
+    server.registerPrompt(
+      p.name,
+      { title: p.name, description: p.description },
+      async () => {
+        const full = getPrompt(root, p.name);
+        const content = full?.content ?? `Agent "${p.name}" is not installed.`;
+        return { messages: [{ role: "user", content: { type: "text", text: content } }] };
+      }
+    );
+  }
+  for (const s of installedSkills) {
+    server.registerPrompt(
+      `skill-${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).` },
+      async () => {
+        const full = getSkill(root, s.id);
+        const content = full?.content ?? `Skill "${s.id}" is not installed.`;
         return { messages: [{ role: "user", content: { type: "text", text: content } }] };
       }
     );