@kaddo/mcp 3.61.0 → 3.62.0

package/dist/index.js

@@ -475,8 +475,8 @@ function loadConfig(dir) {
   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}`;
+      const path4 = i.path.join(".");
+      return path4 ? `  - ${path4}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -829,11 +829,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path3 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path3)) return [];
+  const path4 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path4)) return [];
   let parsed;
   try {
-    parsed = parseYaml4(readFile(path3));
+    parsed = parseYaml4(readFile(path4));
   } catch {
     return [];
   }
@@ -2283,7 +2283,7 @@ function sectionParagraph2(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path3, md) {
+function parseCapsule(id, path4, md) {
   const { data } = matter4(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -2293,7 +2293,7 @@ function parseCapsule(id, path3, md) {
   }
   return {
     id,
-    path: path3,
+    path: path4,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -2355,9 +2355,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path3 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
-    if (path3) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path3 });
+    const path4 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
+    if (path4) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path4 });
       presentLayers.push(layer2.id);
     }
   }
@@ -3834,6 +3834,7 @@ function buildDeliveryState(dir) {
     refined_draft_ids: wis.filter((w3) => w3.lifecycle === "draft" && w3.rawFrontmatter.refined_by).map((w3) => w3.id),
     ready_work_items: byState("ready"),
     ready_work_item_ids: wis.filter((w3) => w3.lifecycle === "ready").map((w3) => w3.id),
+    ready_multirepo_wi_ids: wis.filter((w3) => w3.lifecycle === "ready" && Array.isArray(w3.rawFrontmatter?.affected_modules) && w3.rawFrontmatter.affected_modules.length > 0).map((w3) => w3.id),
     in_progress_work_items: byState("in-progress"),
     blocked_work_items: byState("blocked"),
     total_work_items: total,
@@ -3966,10 +3967,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const discovery = state === "pre-ai" || state === "legacy";
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path3 = agentInstallPath(file);
-    const installed = isFile(join(dir, path3));
+    const path4 = agentInstallPath(file);
+    const installed = isFile(join(dir, path4));
     const group = agentGroupOf(file);
-    return { agentPath: path3, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const refine = (id, agent, target, quality, verb = "complete") => {
     const ar = resolveAgent(agent);
@@ -4026,6 +4027,13 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
         reason: "The roadmap has no candidates yet, but ready Work Items exist."
       });
     }
+    if (st.ready_multirepo_wi_ids.length > 0) {
+      sec.push({
+        id: "validate-work-item-modules",
+        label: "Validate affected modules for multirepo Work Items before implementation.",
+        reason: `${st.ready_multirepo_wi_ids.length} ready Work Item(s) reference affected_modules.`
+      });
+    }
     if (adapters === 0) {
       return {
         id: "prepare-implementation",
@@ -7705,7 +7713,8 @@ function mapNextStepId(id) {
     "implement-work-item": "prepare-implementation",
     "refine-module-context": "refine-work-item",
     "init-module-context": "enable-kaddo",
-    "module-ready": "prepare-implementation"
+    "module-ready": "prepare-implementation",
+    "validate-work-item-modules": "prepare-implementation"
   };
   return MAP[id] ?? id;
 }
@@ -8527,7 +8536,7 @@ function buildGuardHistory(dir) {
     const d3 = hotspotDir(t.code_path);
     hotspotMap.set(d3, (hotspotMap.get(d3) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path3, warnings]) => ({ path: path3, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path4, warnings]) => ({ path: path4, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -9924,8 +9933,462 @@ function listGraphHints(root, filter = {}) {
   });
 }
 
-// ../cli/src/core/context-pack.ts
+// src/multirepo.ts
+import fs3 from "fs";
+import path3 from "path";
 import matter11 from "gray-matter";
+import { parse as parseYaml8 } from "yaml";
+var ok2 = (data) => ({ ok: true, data });
+var fail2 = (message) => ({ ok: false, message });
+function loadModulesDescriptor(root) {
+  return readYaml(root, ".kaddo/modules.yml") ?? { modules: [] };
+}
+function loadConfig2(root) {
+  return readYaml(root, ".kaddo/config.yml");
+}
+function projectRole2(config) {
+  return config.project?.role ?? config.multirepo?.role;
+}
+function isCore(config) {
+  return projectRole2(config) === "core";
+}
+function readModuleFile(root, repoPath, relFile) {
+  const moduleDir = path3.resolve(root, repoPath);
+  const abs = path3.resolve(moduleDir, relFile);
+  if (!abs.startsWith(moduleDir)) return null;
+  if (!fs3.existsSync(abs) || !fs3.statSync(abs).isFile()) return null;
+  return fs3.readFileSync(abs, "utf-8");
+}
+function detectModuleStatus2(root, repoPath) {
+  const moduleDir = path3.resolve(root, repoPath);
+  if (!fs3.existsSync(moduleDir)) {
+    return { status: "missing", configured: false, moduleContext: false, currentState: false, codebase: false, warning: `Directory \`${repoPath}\` does not exist.` };
+  }
+  const configPath = path3.join(moduleDir, ".kaddo", "config.yml");
+  if (!fs3.existsSync(configPath)) {
+    return { status: "not_configured", configured: false, moduleContext: false, currentState: false, codebase: false, warning: `Run \`kaddo init\` inside \`${repoPath}\` and select multirepo \u2192 module.` };
+  }
+  let parsed = null;
+  try {
+    parsed = parseYaml8(fs3.readFileSync(configPath, "utf-8"));
+  } catch {
+  }
+  const role = parsed?.project?.role ?? parsed?.multirepo?.role;
+  if (role !== "module") {
+    return { status: "invalid", configured: true, role, moduleContext: false, currentState: false, codebase: false, warning: `Repository has Kaddo configured but project.role is not module.` };
+  }
+  return {
+    status: "configured",
+    configured: true,
+    role: "module",
+    moduleContext: fs3.existsSync(path3.join(moduleDir, "knowledge", "module", "module-context.md")),
+    currentState: fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "current-state.md")),
+    codebase: fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "codebase.md"))
+  };
+}
+function isPlaceholder(content) {
+  const body = content.replace(/^---[\s\S]*?---\n?/, "");
+  return /^_[^_]+_$/m.test(body) && !body.split("\n").some((l2) => l2.trim().length > 0 && !l2.startsWith("#") && !l2.startsWith("_") && !l2.startsWith("-") && !l2.startsWith(">"));
+}
+function firstParagraph3(md) {
+  const body = md.replace(/^---[\s\S]*?---\n?/, "");
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">") && !t.startsWith("_")) return t.replace(/\s+/g, " ");
+  }
+  return "";
+}
+function slugify2(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
+function modulesListTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found. Run `kaddo init` first.");
+  if (!isCore(config)) return fail2("kaddo_modules_list can only be called from a core repository (project.role: core).");
+  const descriptor = loadModulesDescriptor(root);
+  const modules = (descriptor.modules ?? []).map((m2) => {
+    const st = detectModuleStatus2(root, m2.repoPath);
+    const entry = {
+      id: m2.id,
+      repo: m2.repoPath,
+      status: st.status,
+      kaddo: {
+        configured: st.configured,
+        role: st.role,
+        moduleContext: st.moduleContext,
+        currentState: st.currentState,
+        codebase: st.codebase
+      }
+    };
+    if (args.includeWarnings && st.warning) entry.warning = st.warning;
+    return entry;
+  });
+  return ok2({
+    project: { name: config.project?.name ?? "unknown", structure: config.project?.structure ?? "unknown", role: "core" },
+    modules
+  });
+}
+function getModuleContextTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found.");
+  const descriptor = loadModulesDescriptor(root);
+  const mod = (descriptor.modules ?? []).find((m2) => m2.id === args.module);
+  if (!mod) return fail2(`Module "${args.module}" not found in .kaddo/modules.yml.`);
+  const st = detectModuleStatus2(root, mod.repoPath);
+  const warnings = [];
+  if (st.status !== "configured") {
+    if (st.warning) warnings.push(st.warning);
+    return ok2({
+      module: { id: mod.id, status: st.status },
+      context: null,
+      warnings,
+      recommendedNextStep: { label: "Initialize module repository with Kaddo.", command: "kaddo init" }
+    });
+  }
+  const mcContent = readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md");
+  const context = {
+    moduleContextPath: `${mod.repoPath}/knowledge/module/module-context.md`,
+    moduleContext: mcContent ?? null
+  };
+  if (mcContent && isPlaceholder(mcContent)) {
+    warnings.push("module-context.md still contains placeholder sections.");
+  }
+  if (args.includeTech) {
+    const cs = readModuleFile(root, mod.repoPath, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, mod.repoPath, "knowledge/tech/codebase.md");
+    context.currentStatePath = `${mod.repoPath}/knowledge/tech/current-state.md`;
+    context.currentStateSummary = cs ? firstParagraph3(cs) : null;
+    context.codebasePath = `${mod.repoPath}/knowledge/tech/codebase.md`;
+    context.codebaseSummary = cb ? firstParagraph3(cb) : null;
+    if (!cs) warnings.push("current-state.md not found in module repository.");
+    if (!cb) warnings.push("codebase.md not found in module repository.");
+  }
+  return ok2({
+    module: { id: mod.id, repo: mod.repoPath, status: "configured" },
+    context,
+    warnings: args.includeWarnings ? warnings : []
+  });
+}
+function validateWorkItemModulesTool(root, args) {
+  const items = listWorkItems(root);
+  const wi = items.find((w3) => w3.id === args.workItemId);
+  if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
+  const raw = readText(root, wi.path);
+  if (!raw) return fail2(`Could not read Work Item file.`);
+  const parsed = matter11(raw);
+  const data = parsed.data;
+  const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
+  const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
+  const descriptor = loadModulesDescriptor(root);
+  const mapped = new Set((descriptor.modules ?? []).map((m2) => m2.id));
+  const warnings = [];
+  const errors = [];
+  if (affectedModules.length === 0) {
+    warnings.push("Work Item has no affected_modules declared.");
+  }
+  const moduleValidations = affectedModules.map((modId) => {
+    if (!mapped.has(modId)) {
+      errors.push(`Module "${modId}" is not in .kaddo/modules.yml.`);
+      return { id: modId, status: "not_mapped", hasModuleContext: false, hasCurrentState: false, hasCodebase: false, hasOwnership: false };
+    }
+    const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
+    const st = detectModuleStatus2(root, mod.repoPath);
+    if (st.status !== "configured") {
+      warnings.push(`Module "${modId}" is ${st.status}.`);
+    }
+    const mcContent = st.moduleContext ? readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md") : null;
+    if (mcContent && isPlaceholder(mcContent)) {
+      warnings.push(`Module "${modId}" has placeholder module-context.`);
+    }
+    const hasOwnership = codeEntries.some((c) => c.repo && (c.repo === mod.repoPath || c.repo.endsWith(`/${modId}`) || c.repo.includes(modId)));
+    return { id: modId, status: st.status, hasModuleContext: st.moduleContext, hasCurrentState: st.currentState, hasCodebase: st.codebase, hasOwnership };
+  });
+  for (const ce of codeEntries) {
+    if (ce.repo && !affectedModules.some((m2) => ce.repo.includes(m2))) {
+      warnings.push(`code.repo "${ce.repo}" is not listed in affected_modules.`);
+    }
+  }
+  for (const mv of moduleValidations) {
+    if (affectedModules.includes(mv.id) && !mv.hasOwnership) {
+      warnings.push(`Module "${mv.id}" is in affected_modules but has no paths in code.`);
+    }
+  }
+  return ok2({
+    workItem: { id: wi.id, title: wi.title, status: wi.status, scope: affectedModules.length > 0 ? "multirepo" : "single", affectedModules },
+    validation: { valid: errors.length === 0, modules: moduleValidations, warnings, errors }
+  });
+}
+function getWorkItemContextTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found.");
+  const items = listWorkItems(root);
+  const wi = items.find((w3) => w3.id === args.workItemId);
+  if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
+  const raw = readText(root, wi.path);
+  if (!raw) return fail2(`Could not read Work Item file.`);
+  const parsed = matter11(raw);
+  const data = parsed.data;
+  const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
+  const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
+  const descriptor = loadModulesDescriptor(root);
+  const warnings = [];
+  const modules = affectedModules.map((modId) => {
+    const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
+    if (!mod) {
+      warnings.push(`Module "${modId}" not in modules.yml.`);
+      return { id: modId, repo: null, moduleContext: null, currentStateSummary: null, codebaseSummary: null };
+    }
+    const st = detectModuleStatus2(root, mod.repoPath);
+    if (st.status !== "configured") warnings.push(`Module "${modId}" is ${st.status}.`);
+    const mc = args.includeModuleContexts !== false ? readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md") : null;
+    const cs = readModuleFile(root, mod.repoPath, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, mod.repoPath, "knowledge/tech/codebase.md");
+    return { id: modId, repo: mod.repoPath, moduleContext: mc, currentStateSummary: cs ? firstParagraph3(cs) : null, codebaseSummary: cb ? firstParagraph3(cb) : null };
+  });
+  const ownership = { crossRepo: codeEntries.length > 1, items: codeEntries.filter((c) => c.repo).map((c) => ({ repo: c.repo, paths: c.paths ?? [] })) };
+  const result = {
+    project: { name: config.project?.name ?? "unknown", role: projectRole2(config) ?? "unknown", structure: config.project?.structure ?? "unknown" },
+    workItem: { id: wi.id, title: wi.title, status: wi.status, affectedModules, acceptanceCriteria: extractSection(parsed.content, "Acceptance criteria"), outOfScope: extractSection(parsed.content, "Out of scope") },
+    modules,
+    ownership,
+    warnings
+  };
+  if (args.includeBranchStrategy !== false && affectedModules.length > 0) {
+    result.branchStrategy = buildBranchStrategy(wi, affectedModules, codeEntries, descriptor);
+  }
+  if (args.includeGuardExpectations) {
+    result.guardExpectations = [
+      "Run guard from core before closing the Work Item.",
+      "Validate ownership across all affected repos."
+    ];
+  }
+  return ok2(result);
+}
+function extractSection(content, heading) {
+  const re = new RegExp(`^##\\s+${heading}\\s*$`, "im");
+  const lines = content.split(/\r?\n/);
+  const start = lines.findIndex((l2) => re.test(l2));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) break;
+    const m2 = lines[i].match(/^\s*-\s*\[[ x]?\]\s*(.+?)\s*$/);
+    if (m2) out.push(m2[1]);
+  }
+  return out;
+}
+function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
+  const slug4 = slugify2(wi.title);
+  const wiLower = wi.id.toLowerCase();
+  const coreBranch = `feature/${wiLower}-${slug4}`;
+  const moduleBranches = {};
+  const commitMessages = {};
+  for (const modId of affectedModules) {
+    const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
+    const repo = mod?.repoPath ?? modId;
+    moduleBranches[repo] = `feature/${wiLower}-${modId}-${slug4.slice(0, 20)}`;
+    commitMessages[repo] = `fix(${wiLower}): update ${modId}`;
+  }
+  commitMessages["core"] = `docs(${wiLower}): capture cross-repo implementation summary`;
+  return {
+    type: affectedModules.length > 0 ? "multi-repo" : "single-repo",
+    branches: { core: coreBranch, modules: moduleBranches },
+    commitMessages,
+    checklist: [
+      "Create branches manually in each repo.",
+      "Implement changes in affected module repos.",
+      "Run validation per repo.",
+      "Run Kaddo guard from core.",
+      "Review diffs manually.",
+      "Commit only with explicit human confirmation."
+    ]
+  };
+}
+function suggestBranchStrategyTool(root, args) {
+  const items = listWorkItems(root);
+  const wi = items.find((w3) => w3.id === args.workItemId);
+  if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
+  const raw = readText(root, wi.path);
+  if (!raw) return fail2(`Could not read Work Item file.`);
+  const parsed = matter11(raw);
+  const data = parsed.data;
+  const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
+  const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
+  const descriptor = loadModulesDescriptor(root);
+  const strategy = buildBranchStrategy(wi, affectedModules, codeEntries, descriptor);
+  return ok2({
+    workItem: { id: wi.id, title: wi.title },
+    strategy,
+    safety: { gitCommandsExecuted: false, message: "Kaddo only suggests branch and commit strategy. It does not execute git commands." }
+  });
+}
+function exportCapsuleTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found.");
+  const role = projectRole2(config);
+  const warnings = [];
+  let capsuleType;
+  let capsuleName;
+  let capsuleData;
+  if (args.module) {
+    if (role === "core") {
+      const descriptor = loadModulesDescriptor(root);
+      const mod = (descriptor.modules ?? []).find((m2) => m2.id === args.module);
+      if (!mod) return fail2(`Module "${args.module}" not found in .kaddo/modules.yml.`);
+      const mc = readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md");
+      if (!mc) warnings.push("module-context.md not found for this module.");
+      if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
+      capsuleType = "module";
+      capsuleName = `${slugify2(config.project?.name ?? "project")}-${args.module}`;
+      capsuleData = {
+        type: "knowledge-capsule",
+        system: `${config.project?.name ?? "unknown"}/${args.module}`,
+        version: 1,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        owner: mod.owner ?? "unknown",
+        source_project: config.project?.name ?? "unknown",
+        purpose: mc ? firstParagraph3(mc) : "",
+        responsibilities: [],
+        capabilities: mod.capabilities ?? [],
+        contracts: [],
+        dependencies: [],
+        knownRisks: [],
+        owners: mod.owner ? [mod.owner] : []
+      };
+    } else if (role === "module") {
+      const mc = readText(root, "knowledge/module/module-context.md");
+      if (!mc) warnings.push("module-context.md not found.");
+      if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
+      const modId = config.module?.id ?? args.module;
+      capsuleType = "module";
+      capsuleName = slugify2(modId);
+      capsuleData = {
+        type: "knowledge-capsule",
+        system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
+        version: 1,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        purpose: mc ? firstParagraph3(mc) : "",
+        responsibilities: [],
+        capabilities: [],
+        contracts: [],
+        dependencies: [],
+        knownRisks: [],
+        owners: []
+      };
+    } else {
+      return fail2("Cannot export module capsule: project role is neither core nor module.");
+    }
+  } else if (args.scope === "system") {
+    if (role !== "core") return fail2("--scope system can only be used from a core repository.");
+    const descriptor = loadModulesDescriptor(root);
+    const responsibilities = [];
+    for (const m2 of descriptor.modules ?? []) {
+      const mc = readModuleFile(root, m2.repoPath, "knowledge/module/module-context.md");
+      responsibilities.push(mc ? `[${m2.id}] ${firstParagraph3(mc) || m2.name || m2.id}` : `[${m2.id}] ${m2.name || m2.id} (no module-context)`);
+    }
+    capsuleType = "system";
+    capsuleName = `${slugify2(config.project?.name ?? "project")}-system`;
+    capsuleData = {
+      type: "knowledge-capsule",
+      system: config.project?.name ?? "unknown",
+      version: 1,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+      purpose: "",
+      responsibilities,
+      capabilities: [],
+      contracts: [],
+      dependencies: [],
+      knownRisks: [],
+      owners: []
+    };
+  } else {
+    if (role === "module") {
+      const mc = readText(root, "knowledge/module/module-context.md");
+      if (!mc) warnings.push("module-context.md not found.");
+      if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
+      const modId = config.module?.id ?? "module";
+      capsuleType = "module";
+      capsuleName = slugify2(modId);
+      capsuleData = {
+        type: "knowledge-capsule",
+        system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
+        version: 1,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        purpose: mc ? firstParagraph3(mc) : "",
+        responsibilities: [],
+        capabilities: [],
+        contracts: [],
+        dependencies: [],
+        knownRisks: [],
+        owners: []
+      };
+    } else {
+      capsuleType = "project";
+      capsuleName = slugify2(config.project?.name ?? "project");
+      capsuleData = {
+        type: "knowledge-capsule",
+        system: config.project?.name ?? "unknown",
+        version: 1,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
+        purpose: "",
+        responsibilities: [],
+        capabilities: [],
+        contracts: [],
+        dependencies: [],
+        knownRisks: [],
+        owners: []
+      };
+    }
+  }
+  const jsonPath = `.kaddo/exports/${capsuleName}.capsule.json`;
+  const mdPath = `.kaddo/exports/${capsuleName}.capsule.md`;
+  const jsonContent = JSON.stringify(capsuleData, null, 2) + "\n";
+  const mdContent = renderCapsuleMd(capsuleData);
+  writeDerived(root, jsonPath, jsonContent);
+  writeDerived(root, mdPath, mdContent);
+  return ok2({ exported: true, type: capsuleType, module: args.module ?? void 0, paths: { json: jsonPath, md: mdPath }, warnings });
+}
+function renderCapsuleMd(data) {
+  const fm = ["---", `type: knowledge-capsule`, `system: ${data.system}`, `version: ${data.version}`, `updated_at: ${data.updated_at}`, "---", ""].join("\n");
+  const list2 = (items) => items.length === 0 ? "_To be completed._" : items.map((i) => `- ${i}`).join("\n");
+  return [
+    fm,
+    `# ${data.system} \u2014 Knowledge Capsule
+`,
+    `## Purpose
+
+${data.purpose || "_To be completed._"}
+`,
+    `## Responsibilities
+
+${list2(data.responsibilities)}
+`,
+    `## Capabilities
+
+${list2(data.capabilities)}
+`,
+    `## Contracts
+
+${list2(data.contracts)}
+`,
+    `## Dependencies
+
+${list2(data.dependencies)}
+`,
+    `## Known Risks
+
+${list2(data.knownRisks)}
+`,
+    `## Owners
+
+${list2(data.owners)}
+`,
+    "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.\n"
+  ].join("\n");
+}
+
+// ../cli/src/core/context-pack.ts
+import matter12 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR3 = "knowledge";
 function readScanJson(dir) {
@@ -9937,8 +10400,8 @@ function readScanJson(dir) {
     return null;
   }
 }
-function firstParagraph3(markdown) {
-  const body = matter11(markdown).content.trim();
+function firstParagraph4(markdown) {
+  const body = matter12(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -9946,7 +10409,7 @@ function readMarkdownSummary(dir, file) {
   const p = join(dir, ARCH_DIR3, file);
   if (!exists(p)) return null;
   try {
-    return firstParagraph3(readFile(p));
+    return firstParagraph4(readFile(p));
   } catch {
     return null;
   }
@@ -11112,6 +11575,72 @@ function createServer(root) {
     { title: "Get skill", description: "Get an installed reusable skill by id.", inputSchema: { id: z3.string() } },
     async (args) => toolText(guarded(root, () => getSkillTool(root, args.id)))
   );
+  server.registerTool(
+    "kaddo_modules_list",
+    {
+      title: "List multirepo modules",
+      description: "List mapped modules and their Kaddo configuration status. Only works from a core repository.",
+      inputSchema: { includeWarnings: z3.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => modulesListTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_get_module_context",
+    {
+      title: "Get module context",
+      description: "Get the local knowledge context (module-context.md, tech files) for a mapped module.",
+      inputSchema: {
+        module: z3.string(),
+        includeTech: z3.boolean().optional(),
+        includeWarnings: z3.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => getModuleContextTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_validate_work_item_modules",
+    {
+      title: "Validate Work Item modules",
+      description: "Validate that a Work Item has coherent affected_modules and sufficient cross-repo ownership.",
+      inputSchema: { workItemId: z3.string() }
+    },
+    async (args) => toolText(guarded(root, () => validateWorkItemModulesTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_get_work_item_context",
+    {
+      title: "Get Work Item context",
+      description: "Composite context for implementing a multirepo Work Item: WI details, affected module contexts, ownership, branch strategy.",
+      inputSchema: {
+        workItemId: z3.string(),
+        includeModuleContexts: z3.boolean().optional(),
+        includeBranchStrategy: z3.boolean().optional(),
+        includeGuardExpectations: z3.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => getWorkItemContextTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_suggest_branch_strategy",
+    {
+      title: "Suggest branch strategy",
+      description: "Suggest branch names, commit messages, and a checklist for a multirepo Work Item. Does NOT execute git.",
+      inputSchema: { workItemId: z3.string() }
+    },
+    async (args) => toolText(guarded(root, () => suggestBranchStrategyTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_export_capsule",
+    {
+      title: "Export Knowledge Capsule",
+      description: "Export a Knowledge Capsule as a derived artifact under .kaddo/exports/. Supports scope=system (from core) and module=<id> (from core or module).",
+      inputSchema: {
+        scope: z3.string().optional(),
+        module: z3.string().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => exportCapsuleTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.61.0",
+  "version": "3.62.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {