@kaddo/mcp 3.62.0 → 3.64.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()
@@ -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";
@@ -685,6 +693,34 @@ function firstUnrefinedLayerAgent(layers) {
   return { agent: "architecture-agent", step: "Use architecture-agent to complete knowledge/tech/current-state.md" };
 }
 function assessPhase(input) {
+  if (input.isModuleRepo) {
+    const techStatus = layer(input.layers, "Tech");
+    const techReady = !NOT_READY_LAYER.includes(techStatus);
+    if (techReady) {
+      return {
+        phase: "Active Delivery",
+        reasons: ["Module repo \u2014 Tech layer ready", "Business/Product managed by core"],
+        recommendedAgents: [],
+        nextStep: "Module knowledge is ready for core orchestration.",
+        llmInstructions: [
+          "This is a module repo. Business, Product, and Delivery are managed by the core repo.",
+          "Do not create business, product, roadmap or Work Items here."
+        ]
+      };
+    }
+    return {
+      phase: "Knowledge Refinement",
+      reasons: ["Module repo \u2014 Tech layer incomplete", "Business/Product managed by core"],
+      recommendedAgents: ["module-context-agent"],
+      nextStep: "Use module-context-agent to refine knowledge/tech/module/module-context.md",
+      llmInstructions: [
+        "Use the module-context-agent to refine the module context.",
+        "Do not create business, product, roadmap or Work Items in this module.",
+        "Do not install agents or skills.",
+        "Do not write application code."
+      ]
+    };
+  }
   const phase = determinePhase(input);
   const reasons = buildReasons(input);
   const bs = input.workItems.byState;
@@ -790,7 +826,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";
@@ -847,7 +883,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 +932,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 +1080,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 +2191,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 +2293,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 [];
@@ -2996,6 +3037,21 @@ function layerQuality(dir, layer2) {
   return worst;
 }
 function knowledgeLayers(dir) {
+  const config = loadConfig(dir);
+  if (config && isModule(config)) {
+    return [
+      { layer: "Business", status: "Not applicable", detected: [] },
+      { layer: "Product", status: "Not applicable", detected: [] },
+      ...discoverLayers(dir).filter((l2) => l2.layer === "Tech").map((l2) => {
+        if (l2.status !== "Consolidated" && l2.status !== "Structured") return l2;
+        const q3 = layerQuality(dir, l2.layer);
+        if (q3 === "placeholder") return { ...l2, status: "Placeholder" };
+        if (q3 === "weak") return { ...l2, status: "Weak" };
+        return l2;
+      }),
+      { layer: "Delivery", status: "Managed by core", detected: [] }
+    ];
+  }
   return discoverLayers(dir).map((l2) => {
     if (l2.status !== "Consolidated" && l2.status !== "Structured") return l2;
     const q3 = layerQuality(dir, l2.layer);
@@ -3693,6 +3749,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"],
@@ -3845,6 +3904,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,12 +3961,20 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   }
   const state = config.project.state;
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
+  const resolveAgent = (agent) => {
+    const file = agent.endsWith(".md") ? agent : `${agent}.md`;
+    const path4 = agentInstallPath(file);
+    const installed = isFile(join(dir, path4));
+    const group = agentGroupOf(file);
+    return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+  };
   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." };
@@ -3908,15 +3983,26 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
       return { id: "context", phase: "Discovery", label: "Run `kaddo context` to prepare the LLM context pack.", command: "kaddo context", reason: "No context pack has been generated yet." };
     }
     if (qMC !== "useful") {
+      const ar = resolveAgent("module-context-agent");
       return {
         id: "refine-module-context",
         phase: "Knowledge Refinement",
-        label: "Use module-context-agent to refine `knowledge/module/module-context.md`.",
+        label: "Use module-context-agent to refine `knowledge/tech/module/module-context.md`.",
         agent: "module-context-agent",
         skill: "module-context-refinement",
         target: MC,
+        agentPath: ar.agentPath,
+        agentInstalled: ar.agentInstalled,
+        installCommand: ar.installCommand,
         reason: "Module context is still a placeholder.",
-        instructions: ["Refine the module context with real knowledge about this module.", "Do not create business.md or product.md.", "Do not write code."]
+        instructions: [
+          "Refine the module context using evidence from this repository.",
+          "Use the parent system context when available.",
+          "Do not create business, product, roadmap or Work Items in this module.",
+          "Do not install agents or skills in this module.",
+          "Do not write application code.",
+          "Preserve frontmatter and record unknowns as open questions."
+        ]
       };
     }
     const qCurrentState2 = q3(CS), qCodebase2 = q3(CB);
@@ -3945,12 +4031,18 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     if (!exists(join(dir, ".kaddo", "understand.md"))) {
       return { id: "understand", phase: "Discovery", label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand", reason: "No understand handoff has been generated yet." };
     }
-    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." };
+    return { id: "module-ready", phase: "Ready for Core Orchestration", label: "Module knowledge is complete. Create and manage Work Items from the core repository.", reason: "This module's knowledge is ready for core orchestration. 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." };
@@ -3965,13 +4057,6 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     return { id: "context", phase: "Discovery", label: "Run `kaddo context` to prepare the LLM context pack.", command: "kaddo context", reason: "No context pack has been generated yet." };
   }
   const discovery = state === "pre-ai" || state === "legacy";
-  const resolveAgent = (agent) => {
-    const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path4 = agentInstallPath(file);
-    const installed = isFile(join(dir, path4));
-    const group = agentGroupOf(file);
-    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);
     return {
@@ -7571,6 +7656,67 @@ var identifyRisks = {
     return { status: hasLegacy ? "done" : "pending", agent: hasLegacy ? void 0 : "legacy-agent" };
   }
 };
+var refineModuleContext = {
+  id: "refine-module-context",
+  label: "Refine module context",
+  evaluate: (ctx) => {
+    const newPath = join(ctx.dir, "knowledge/tech/module/module-context.md");
+    const legacyPath = join(ctx.dir, "knowledge/module/module-context.md");
+    const mcPath = exists(newPath) ? "knowledge/tech/module/module-context.md" : exists(legacyPath) ? "knowledge/module/module-context.md" : null;
+    if (!mcPath) return { status: "pending", agent: "module-context-agent", skill: "module-context-refinement" };
+    const q3 = analyzeKnowledgeArtifact(ctx.dir, mcPath);
+    if (q3 === "useful") return { status: "done", evidence: [mcPath] };
+    return { status: "current", agent: "module-context-agent", skill: "module-context-refinement", evidence: [mcPath], reason: "Module context is still a placeholder." };
+  }
+};
+var describeModuleCurrentState = {
+  id: "describe-current-state",
+  label: "Describe current state",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qCurrentState) ? "done" : "pending",
+    evidence: isUseful(ctx.qCurrentState) ? ["knowledge/tech/current-state.md"] : void 0,
+    agent: isUseful(ctx.qCurrentState) ? void 0 : "architecture-agent"
+  })
+};
+var mapModuleCodebase = {
+  id: "map-codebase",
+  label: "Map codebase",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qCodebase) ? "done" : "pending",
+    evidence: isUseful(ctx.qCodebase) ? ["knowledge/tech/codebase.md"] : void 0,
+    agent: isUseful(ctx.qCodebase) ? void 0 : "architecture-agent"
+  })
+};
+var validateModuleKnowledge = {
+  id: "validate-module-knowledge",
+  label: "Validate module knowledge",
+  evaluate: (ctx) => {
+    const hasUnderstand = exists(join(ctx.dir, ".kaddo/understand.md"));
+    if (hasUnderstand) return { status: "done", evidence: [".kaddo/understand.md"] };
+    return { status: "pending", command: "kaddo understand" };
+  }
+};
+var readyForCoreOrchestration = {
+  id: "ready-for-core-orchestration",
+  label: "Ready for core orchestration",
+  evaluate: (ctx) => {
+    const newPath = join(ctx.dir, "knowledge/tech/module/module-context.md");
+    const legacyPath = join(ctx.dir, "knowledge/module/module-context.md");
+    const mcPath = exists(newPath) ? "knowledge/tech/module/module-context.md" : exists(legacyPath) ? "knowledge/module/module-context.md" : null;
+    const mcUseful = mcPath ? analyzeKnowledgeArtifact(ctx.dir, mcPath) === "useful" : false;
+    const allDone = mcUseful && isUseful(ctx.qCurrentState) && isUseful(ctx.qCodebase);
+    return { status: allDone ? "done" : "pending", reason: allDone ? void 0 : "Module knowledge is not yet complete." };
+  }
+};
+var MODULE_STEPS = [
+  enableKaddo,
+  scanRepository,
+  refineModuleContext,
+  describeModuleCurrentState,
+  mapModuleCodebase,
+  validateModuleKnowledge,
+  readyForCoreOrchestration
+];
 var NEW_STEPS = [
   enableKaddo,
   defineBusiness,
@@ -7711,17 +7857,18 @@ function mapNextStepId(id) {
     "review-work-item": "refine-work-item",
     "prepare-implementation": "prepare-implementation",
     "implement-work-item": "prepare-implementation",
-    "refine-module-context": "refine-work-item",
+    "refine-module-context": "refine-module-context",
     "init-module-context": "enable-kaddo",
-    "module-ready": "prepare-implementation",
-    "validate-work-item-modules": "prepare-implementation"
+    "module-ready": "ready-for-core-orchestration",
+    "validate-work-item-modules": "validate-module-knowledge",
+    "modules-discover": "enable-kaddo"
   };
   return MAP[id] ?? id;
 }
 function buildProjectRoute(dir) {
   const config = loadConfig(dir);
   const state = config?.project.state ?? "pre-ai";
-  const defs = stepsForState(state);
+  const defs = config && isModule(config) ? MODULE_STEPS : stepsForState(state);
   const ctx = buildRouteContext(dir);
   const steps = defs.map((d3) => {
     const result = d3.evaluate(ctx);
@@ -8108,7 +8255,8 @@ function buildProjectExplanation(dir) {
     roadmapQuality: buildRoadmapQuality(dir),
     projectRoute: buildProjectRoute(dir),
     scanSignals: loadScanSignals(dir),
-    metadataHealth: analyzeMetadataHealth(dir)
+    metadataHealth: analyzeMetadataHealth(dir),
+    isModuleRepo: config != null && isModule(config)
   };
 }
 function stateLabel(state) {
@@ -8981,7 +9129,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,
@@ -8999,7 +9147,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;
@@ -9837,7 +9985,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") {
@@ -9847,7 +9995,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: {
@@ -9937,9 +10085,12 @@ function listGraphHints(root, filter = {}) {
 import fs3 from "fs";
 import path3 from "path";
 import matter11 from "gray-matter";
-import { parse as parseYaml8 } from "yaml";
+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: [] };
 }
@@ -9949,7 +10100,7 @@ function loadConfig2(root) {
 function projectRole2(config) {
   return config.project?.role ?? config.multirepo?.role;
 }
-function isCore(config) {
+function isCore2(config) {
   return projectRole2(config) === "core";
 }
 function readModuleFile(root, repoPath, relFile) {
@@ -9970,7 +10121,7 @@ function detectModuleStatus2(root, repoPath) {
   }
   let parsed = null;
   try {
-    parsed = parseYaml8(fs3.readFileSync(configPath, "utf-8"));
+    parsed = parseYaml10(fs3.readFileSync(configPath, "utf-8"));
   } catch {
   }
   const role = parsed?.project?.role ?? parsed?.multirepo?.role;
@@ -9981,11 +10132,18 @@ function detectModuleStatus2(root, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: fs3.existsSync(path3.join(moduleDir, "knowledge", "module", "module-context.md")),
+    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(">"));
@@ -10004,13 +10162,14 @@ function slugify2(s) {
 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).");
+  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 st = detectModuleStatus2(root, m2.repoPath);
+    const rp = moduleRepoPath(m2);
+    const st = detectModuleStatus2(root, rp);
     const entry = {
       id: m2.id,
-      repo: m2.repoPath,
+      repo: rp,
       status: st.status,
       kaddo: {
         configured: st.configured,
@@ -10034,7 +10193,8 @@ function getModuleContextTool(root, args) {
   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 rp = moduleRepoPath(mod);
+  const st = detectModuleStatus2(root, rp);
   const warnings = [];
   if (st.status !== "configured") {
     if (st.warning) warnings.push(st.warning);
@@ -10045,26 +10205,27 @@ function getModuleContextTool(root, args) {
       recommendedNextStep: { label: "Initialize module repository with Kaddo.", command: "kaddo init" }
     });
   }
-  const mcContent = readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md");
+  const mcRelPath = resolveModuleContextPath(root, rp);
+  const mcContent = readModuleFile(root, rp, mcRelPath);
   const context = {
-    moduleContextPath: `${mod.repoPath}/knowledge/module/module-context.md`,
+    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, 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`;
+    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 = `${mod.repoPath}/knowledge/tech/codebase.md`;
+    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: mod.repoPath, status: "configured" },
+    module: { id: mod.id, repo: rp, status: "configured" },
     context,
     warnings: args.includeWarnings ? warnings : []
   });
@@ -10092,15 +10253,17 @@ function validateWorkItemModulesTool(root, args) {
       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);
+    const rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
     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;
+    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 === mod.repoPath || c.repo.endsWith(`/${modId}`) || c.repo.includes(modId)));
+    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) {
@@ -10138,12 +10301,14 @@ function getWorkItemContextTool(root, args) {
       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);
+    const rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
     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 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 = {
@@ -10185,7 +10350,7 @@ function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
   const commitMessages = {};
   for (const modId of affectedModules) {
     const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
-    const repo = mod?.repoPath ?? modId;
+    const repo = mod ? moduleRepoPath(mod) || modId : modId;
     moduleBranches[repo] = `feature/${wiLower}-${modId}-${slug4.slice(0, 20)}`;
     commitMessages[repo] = `fix(${wiLower}): update ${modId}`;
   }
@@ -10235,7 +10400,9 @@ function exportCapsuleTool(root, args) {
       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");
+      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";
@@ -10256,7 +10423,7 @@ function exportCapsuleTool(root, args) {
         owners: mod.owner ? [mod.owner] : []
       };
     } else if (role === "module") {
-      const mc = readText(root, "knowledge/module/module-context.md");
+      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;
@@ -10283,7 +10450,9 @@ function exportCapsuleTool(root, args) {
     const descriptor = loadModulesDescriptor(root);
     const responsibilities = [];
     for (const m2 of descriptor.modules ?? []) {
-      const mc = readModuleFile(root, m2.repoPath, "knowledge/module/module-context.md");
+      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";
@@ -10303,7 +10472,7 @@ function exportCapsuleTool(root, args) {
     };
   } else {
     if (role === "module") {
-      const mc = readText(root, "knowledge/module/module-context.md");
+      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";
@@ -10348,6 +10517,70 @@ function exportCapsuleTool(root, args) {
   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");
@@ -10471,15 +10704,16 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   if (!knowledgeSummary) {
     missing.push("No project knowledge summary found yet.");
   }
+  const moduleRepo = config != null && isModule(config);
   const roadmapSummary = readMarkdownSummary(dir, "delivery/roadmap.md") ?? "";
-  if (!roadmapSummary) {
+  if (!roadmapSummary && !moduleRepo) {
     missing.push("No roadmap baseline found.");
   }
   const allArtifacts = discoverKnowledge(dir);
   const workItems = allArtifacts.filter(
     (a2) => isDeliveryWorkItem(a2) && isActiveState(lifecycleStateOf({ status: a2.status, filePath: a2.filePath }))
   );
-  if (workItems.length === 0) {
+  if (workItems.length === 0 && !moduleRepo) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
@@ -10511,8 +10745,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     tech: { status: layerStatusOf("Tech"), artifacts: { "knowledge/tech/codebase.md": qCodebase, "knowledge/tech/current-state.md": qCurrentState } },
     delivery: { status: layerStatusOf("Delivery"), artifacts: { "knowledge/delivery/roadmap.md": qRoadmap } }
   };
-  if (qBusiness === "placeholder") missing.push("Business context exists but still looks like a bootstrap placeholder.");
-  if (qProduct === "placeholder" || qCapabilities === "placeholder") missing.push("Product capabilities exist but still look like a bootstrap placeholder.");
+  if (qBusiness === "placeholder" && !moduleRepo) missing.push("Business context exists but still looks like a bootstrap placeholder.");
+  if ((qProduct === "placeholder" || qCapabilities === "placeholder") && !moduleRepo) missing.push("Product capabilities exist but still look like a bootstrap placeholder.");
   if (qCurrentState === "placeholder") missing.push("Current state exists but still looks like a bootstrap placeholder.");
   if (qCodebase === "placeholder") missing.push("Codebase map exists but still looks like a bootstrap placeholder.");
   const allWorkItems = allArtifacts.filter((a2) => a2.isWorkItem);
@@ -10535,7 +10769,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       workItemsTotal: allWorkItems.length,
       workItemsWithOwnership: wiWithOwnership,
       workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
-    }
+    },
+    isModuleRepo: config != null && isModule(config)
   });
   const nextStepRecommendation = resolveNextStep(dir, now);
   const techDecisions = buildTechDecisions(dir);
@@ -11017,6 +11252,16 @@ function flowForState(state) {
 }
 function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
+  if (isModule(config)) {
+    return {
+      project: { name: config.project.name, state, teamSize: config.team.size, structure: config.project.structure, language: "English" },
+      steps: [],
+      missingAgents: [],
+      agentsInstalled: true,
+      scanAvailable: exists(join(dir, ".kaddo", "scan.json")),
+      contextPackPath: ".kaddo/context-pack.md"
+    };
+  }
   const flow = flowForState(state).filter((s) => !exists(join(dir, s.output)));
   const steps = flow.map((s) => {
     const installed = agentIsInstalled(dir, s.agent);
@@ -11641,6 +11886,18 @@ function createServer(root) {
     },
     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.62.0",
+  "version": "3.64.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {