@kaddo/mcp 3.61.0 → 3.63.0

package/dist/index.js

@@ -168,7 +168,8 @@ var DERIVED_WRITE_FILES = /* @__PURE__ */ new Set([
   ".kaddo/graph.json",
   ".kaddo/graph.mmd",
   ".kaddo/graph-hints.md",
-  ".kaddo/graph-hints.json"
+  ".kaddo/graph-hints.json",
+  ".kaddo/modules.yml"
 ]);
 var DERIVED_EXPORTS_RE = /^\.kaddo\/exports\/[^/]+\.capsule\.(md|json)$/;
 var DERIVED_REPORTS_RE = /^\.kaddo\/reports\/[^/]+\.(md|json)$/;
@@ -447,10 +448,14 @@ var configSchema = z.object({
   team: z.object({
     size: teamSizeSchema.default(DEFAULTS.teamSize)
   }).passthrough().default({}),
+  system: z.object({
+    name: z.string().optional()
+  }).passthrough().optional(),
   multirepo: z.object({
     role: multirepoRoleSchema,
     modules_file: z.string().optional(),
-    parent_system: z.string().optional()
+    parent_system: z.string().optional(),
+    workspace_roots: z.array(z.string()).optional()
   }).passthrough().optional(),
   module: z.object({
     id: z.string().optional()
@@ -475,8 +480,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}`);
@@ -489,6 +494,9 @@ function projectRole(config) {
 function isModule(config) {
   return projectRole(config) === "module";
 }
+function isCore(config) {
+  return projectRole(config) === "core";
+}
 
 // ../cli/src/services/artifact-reader.ts
 import matter3 from "gray-matter";
@@ -790,7 +798,7 @@ function assessPhase(input) {
 
 // ../cli/src/core/capsule.ts
 import matter4 from "gray-matter";
-import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
+import { parse as parseYaml7, stringify as stringifyYaml3 } from "yaml";
 
 // ../cli/src/services/owners.ts
 import { parse as parseYaml3 } from "yaml";
@@ -829,11 +837,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 [];
   }
@@ -847,7 +855,7 @@ function loadMappedModules(dir) {
     modules.push({
       id,
       name: typeof m2.name === "string" ? m2.name : void 0,
-      repoPath: typeof m2.repoPath === "string" ? m2.repoPath : "",
+      repoPath: typeof m2.repoPath === "string" ? m2.repoPath : typeof m2.path === "string" ? m2.path : "",
       type: typeof m2.type === "string" ? m2.type : void 0,
       mainTechnology: typeof m2.mainTechnology === "string" ? m2.mainTechnology : void 0,
       owner: typeof m2.owner === "string" ? m2.owner : void 0,
@@ -896,13 +904,15 @@ function detectModuleStatus(coreDir, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: exists(join(moduleDir, "knowledge", "module", "module-context.md")),
+    moduleContext: exists(join(moduleDir, "knowledge", "tech", "module", "module-context.md")) || exists(join(moduleDir, "knowledge", "module", "module-context.md")),
     currentState: exists(join(moduleDir, "knowledge", "tech", "current-state.md")),
     codebase: exists(join(moduleDir, "knowledge", "tech", "codebase.md"))
   };
 }
 function readModuleContext(coreDir, repoPath) {
-  const p = join(coreDir, repoPath, "knowledge", "module", "module-context.md");
+  const newPath = join(coreDir, repoPath, "knowledge", "tech", "module", "module-context.md");
+  const legacyPath = join(coreDir, repoPath, "knowledge", "module", "module-context.md");
+  const p = exists(newPath) ? newPath : legacyPath;
   if (!exists(p)) return null;
   try {
     return readFile(p);
@@ -1042,7 +1052,7 @@ var Q2 = o("\u25B2", "!");
 var ee = o("\u25A0", "x");
 
 // ../cli/src/commands/modules-map.ts
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
 
 // ../cli/src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -2153,6 +2163,9 @@ ${QUALITY}
 - [ ] The next step is clear.
 `;
 
+// ../cli/src/commands/modules-discover.ts
+import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+
 // ../cli/src/core/capsule.ts
 var KNOWLEDGE2 = "knowledge";
 function today() {
@@ -2252,7 +2265,7 @@ function loadExternalRegistry(dir) {
   const p = join(dir, EXTERNAL_PATH);
   if (!exists(p)) return [];
   try {
-    const parsed = parseYaml6(readFile(p));
+    const parsed = parseYaml7(readFile(p));
     return Array.isArray(parsed?.external) ? parsed.external : [];
   } catch {
     return [];
@@ -2283,7 +2296,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 +2306,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 +2368,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);
     }
   }
@@ -3693,6 +3706,9 @@ function buildAdapterStatuses(dir) {
   });
 }
 
+// ../cli/src/core/next-step.ts
+import { parse as parseYaml8 } from "yaml";
+
 // ../cli/src/agents/groups.ts
 var AGENT_GROUPS = {
   business: ["business-agent.md"],
@@ -3834,6 +3850,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,
@@ -3844,6 +3861,14 @@ function buildDeliveryState(dir) {
     adapters_installed: adapters.length
   };
 }
+function hasRegisteredModules(modulesYmlPath) {
+  try {
+    const parsed = parseYaml8(readFile(modulesYmlPath));
+    return Array.isArray(parsed?.modules) && parsed.modules.length > 0;
+  } catch {
+    return false;
+  }
+}
 function safeRead(p) {
   try {
     return readFile(p);
@@ -3894,11 +3919,12 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const state = config.project.state;
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const moduleRepo = isModule(config);
-  const MC = "knowledge/module/module-context.md";
+  const coreRepo = isCore(config);
+  const MC = exists(join(dir, "knowledge/tech/module/module-context.md")) ? "knowledge/tech/module/module-context.md" : "knowledge/module/module-context.md";
   if (moduleRepo) {
     const qMC = q3(MC);
     if (qMC === "missing") {
-      return { id: "init-module-context", phase: "Setup", label: "Create `knowledge/module/module-context.md` for this module.", command: "kaddo init", reason: "Module context file is missing. Re-run `kaddo init` as a multirepo module." };
+      return { id: "init-module-context", phase: "Setup", label: "Create `knowledge/tech/module/module-context.md` for this module.", command: "kaddo init", reason: "Module context file is missing. Re-run `kaddo init` as a multirepo module." };
     }
     if ((state === "pre-ai" || state === "legacy") && !exists(join(dir, ".kaddo", "scan.json"))) {
       return { id: "scan", phase: "Discovery", label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan", reason: "No scan baseline exists for this existing project yet." };
@@ -3947,9 +3973,15 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     return { id: "module-ready", phase: "Active Delivery", label: "Module context is complete. Create and manage Work Items from the core repository.", reason: "This module's knowledge is ready. Work Items are created and tracked in the core." };
   }
   const qBusiness = q3(B2), qProduct = q3(P2), qCap = q3(CAP), qCurrentState = q3(CS), qCodebase = q3(CB);
-  if (qBusiness === "missing" || qProduct === "missing") {
+  if (!coreRepo && (qBusiness === "missing" || qProduct === "missing")) {
     return { id: "bootstrap", phase: "Setup", label: "Run `kaddo bootstrap` to create the project knowledge baseline.", command: "kaddo bootstrap", reason: "The knowledge baseline is incomplete." };
   }
+  if (coreRepo) {
+    const modulesYmlPath = join(dir, ".kaddo", "modules.yml");
+    if (!exists(modulesYmlPath) || !hasRegisteredModules(modulesYmlPath)) {
+      return { id: "modules-discover", phase: "Setup", label: "Run `kaddo modules discover` to find sibling module repositories.", command: "kaddo modules discover", reason: "No modules are mapped for this core repository." };
+    }
+  }
   const ctx = buildCodexAdapterContext(dir);
   if (!ctx.hasAgents) {
     return { id: "add-agents", phase: "Setup", label: "Run `kaddo add agents` to install the Kaddo agent prompt packs.", command: "kaddo add agents", reason: "No Kaddo agents are installed yet." };
@@ -3966,10 +3998,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 +4058,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 +7744,9 @@ 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",
+    "modules-discover": "enable-kaddo"
   };
   return MAP[id] ?? id;
 }
@@ -8527,7 +8568,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,
@@ -8972,7 +9013,7 @@ function serializeImpactJson(r2) {
 }
 
 // ../cli/src/core/savings.ts
-import { parse as parseYaml7 } from "yaml";
+import { parse as parseYaml9 } from "yaml";
 var DEFAULT_ASSUMPTIONS = {
   currency: "USD",
   hourly_cost: 40,
@@ -8990,7 +9031,7 @@ function loadAssumptions(dir) {
   const p = join(dir, SAVINGS_PATH);
   if (!exists(p)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
   try {
-    const raw = parseYaml7(readFile(p));
+    const raw = parseYaml9(readFile(p));
     const a2 = raw?.assumptions ?? {};
     const t = raw?.team ?? {};
     const num = (v, d3) => typeof v === "number" && Number.isFinite(v) ? v : d3;
@@ -9828,7 +9869,7 @@ function getWorkItem(root, id) {
   const content = readText(root, item.path);
   return ok({ ...item, content: content ?? "" });
 }
-function markWorkItemReady(root, id, confirm) {
+function markWorkItemReady(root, id, confirm2) {
   const item = listWorkItems(root).find((w3) => w3.id === id);
   if (!item) return fail(`Work Item "${id}" not found.`);
   if (item.status === "ready") {
@@ -9838,7 +9879,7 @@ function markWorkItemReady(root, id, confirm) {
     return fail(`Work Item ${item.id} is in state "${item.status}", not "draft". Only draft Work Items can be marked as ready.`);
   }
   const warnings = item.readiness?.warnings ?? [];
-  if (!confirm) {
+  if (!confirm2) {
     return ok({
       status: "needs_confirmation",
       workItem: {
@@ -9924,8 +9965,547 @@ 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 parseYaml10, stringify as stringifyYaml4 } from "yaml";
+var ok2 = (data) => ({ ok: true, data });
+var fail2 = (message) => ({ ok: false, message });
+function moduleRepoPath(m2) {
+  return m2.path ?? m2.repoPath ?? "";
+}
+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 isCore2(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 = parseYaml10(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", "tech", "module", "module-context.md")) || 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 resolveModuleContextPath(root, repoPath) {
+  const moduleDir = path3.resolve(root, repoPath);
+  if (fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "module", "module-context.md"))) {
+    return "knowledge/tech/module/module-context.md";
+  }
+  return "knowledge/module/module-context.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 (!isCore2(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 rp = moduleRepoPath(m2);
+    const st = detectModuleStatus2(root, rp);
+    const entry = {
+      id: m2.id,
+      repo: rp,
+      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 rp = moduleRepoPath(mod);
+  const st = detectModuleStatus2(root, rp);
+  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 mcRelPath = resolveModuleContextPath(root, rp);
+  const mcContent = readModuleFile(root, rp, mcRelPath);
+  const context = {
+    moduleContextPath: `${rp}/${mcRelPath}`,
+    moduleContext: mcContent ?? null
+  };
+  if (mcContent && isPlaceholder(mcContent)) {
+    warnings.push("module-context.md still contains placeholder sections.");
+  }
+  if (args.includeTech) {
+    const cs = readModuleFile(root, rp, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, rp, "knowledge/tech/codebase.md");
+    context.currentStatePath = `${rp}/knowledge/tech/current-state.md`;
+    context.currentStateSummary = cs ? firstParagraph3(cs) : null;
+    context.codebasePath = `${rp}/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: rp, 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 rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
+    if (st.status !== "configured") {
+      warnings.push(`Module "${modId}" is ${st.status}.`);
+    }
+    const mcRelPath = resolveModuleContextPath(root, rp);
+    const mcContent = st.moduleContext ? readModuleFile(root, rp, mcRelPath) : null;
+    if (mcContent && isPlaceholder(mcContent)) {
+      warnings.push(`Module "${modId}" has placeholder module-context.`);
+    }
+    const hasOwnership = codeEntries.some((c) => c.repo && (c.repo === rp || 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 rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
+    if (st.status !== "configured") warnings.push(`Module "${modId}" is ${st.status}.`);
+    const mcRelPath = resolveModuleContextPath(root, rp);
+    const mc = args.includeModuleContexts !== false ? readModuleFile(root, rp, mcRelPath) : null;
+    const cs = readModuleFile(root, rp, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, rp, "knowledge/tech/codebase.md");
+    return { id: modId, repo: rp, 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 ? moduleRepoPath(mod) || modId : 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 rp = moduleRepoPath(mod);
+      const mcRelPath = resolveModuleContextPath(root, rp);
+      const mc = readModuleFile(root, rp, mcRelPath);
+      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/tech/module/module-context.md") ?? 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 rp = moduleRepoPath(m2);
+      const mcRelPath = resolveModuleContextPath(root, rp);
+      const mc = readModuleFile(root, rp, mcRelPath);
+      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/tech/module/module-context.md") ?? 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 modulesDiscoverTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found.");
+  if (!isCore2(config)) return fail2("Module discovery is only available from a core repository.");
+  const sysName = config.system?.name ?? config.project?.name ?? "";
+  const workspaceRoots2 = config.multirepo?.workspace_roots ?? [".."];
+  const IGNORED = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "coverage", "vendor", ".next", "out", "tmp", "temp", ".kaddo"]);
+  const coreAbs = path3.resolve(root);
+  const discovered = [];
+  for (const wr of workspaceRoots2) {
+    const rootAbs = path3.resolve(root, wr);
+    if (!fs3.existsSync(rootAbs) || !fs3.statSync(rootAbs).isDirectory()) continue;
+    let entries;
+    try {
+      entries = fs3.readdirSync(rootAbs);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (IGNORED.has(entry)) continue;
+      const candidateAbs = path3.resolve(rootAbs, entry);
+      if (!fs3.statSync(candidateAbs).isDirectory()) continue;
+      if (candidateAbs === coreAbs) continue;
+      const relPath = path3.relative(root, candidateAbs).replace(/\\/g, "/");
+      const cfgPath = path3.join(candidateAbs, ".kaddo", "config.yml");
+      if (!fs3.existsSync(cfgPath)) {
+        discovered.push({ id: entry, path: relPath, status: "not_configured", eligibleForMapping: false });
+        continue;
+      }
+      let parsed = null;
+      try {
+        parsed = parseYaml10(fs3.readFileSync(cfgPath, "utf-8"));
+      } catch {
+      }
+      const role = parsed?.project?.role ?? parsed?.multirepo?.role;
+      if (role !== "module") {
+        discovered.push({ id: entry, path: relPath, status: "invalid", eligibleForMapping: false, warning: "Not configured as module." });
+        continue;
+      }
+      const modParent = parsed?.multirepo?.parent_system ?? "";
+      if (modParent && modParent !== sysName) {
+        discovered.push({ id: parsed?.module?.id ?? entry, path: relPath, status: "foreign_system", eligibleForMapping: false, parentSystem: modParent });
+        continue;
+      }
+      discovered.push({ id: parsed?.module?.id ?? entry, path: relPath, status: "configured", eligibleForMapping: true });
+    }
+  }
+  if (args.apply) {
+    if (!args.confirm) {
+      return ok2({ discovered, applied: false, message: "Set confirm: true to apply discovered modules." });
+    }
+    const descriptor = loadModulesDescriptor(root);
+    for (const d3 of discovered.filter((dd) => dd.eligibleForMapping)) {
+      if (!(descriptor.modules ?? []).some((m2) => m2.id === d3.id)) {
+        if (!descriptor.modules) descriptor.modules = [];
+        descriptor.modules.push({ id: d3.id, name: d3.id, path: d3.path, parent_system: sysName, status: "configured" });
+      }
+    }
+    const ymlContent = stringifyYaml4({ version: descriptor.version ?? 1, system: sysName, workspace_roots: workspaceRoots2, modules: descriptor.modules ?? [] });
+    writeDerived(root, ".kaddo/modules.yml", ymlContent);
+    return ok2({ discovered, applied: true });
+  }
+  return ok2({ discovered, applied: false });
+}
+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 +10517,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 +10526,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 +11692,84 @@ 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)))
+  );
+  server.registerTool(
+    "kaddo_modules_discover",
+    {
+      title: "Discover multirepo modules",
+      description: "Discover sibling repositories configured as Kaddo modules. Does not persist without apply+confirm. Core only.",
+      inputSchema: {
+        apply: z3.boolean().optional(),
+        confirm: z3.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => modulesDiscoverTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

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