@kaddo/mcp 3.48.0 → 3.50.0

package/dist/index.js

@@ -384,6 +384,7 @@ function parseArtifact(filePath, raw) {
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
       source: data.source ? String(data.source) : "",
       sourceId: String(data.source_id ?? ""),
+      rawFrontmatter: data,
       decisions: Array.isArray(data.decisions) ? data.decisions.map(String).filter(Boolean) : [],
       capsules: Array.isArray(data.capsules) ? data.capsules.map(String).filter(Boolean) : []
     };
@@ -2655,7 +2656,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   const ctx = buildCodexAdapterContext(dir);
   const agents = ctx.hasAgents ? "present" : "missing";
   const skills = ctx.hasSkills ? "present" : "missing";
-  const bootstrapBaseline = presence.business !== "missing" && presence.product !== "missing" ? "complete" : "incomplete";
+  const bootstrapBaseline2 = presence.business !== "missing" && presence.product !== "missing" ? "complete" : "incomplete";
   const roadmap = roadmapSignal(dir);
   const work_items = workItemsSignal(dir);
   const adapters = installedAdapters(dir);
@@ -2663,7 +2664,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   const signals = {
     scan,
     understand,
-    bootstrap_baseline: bootstrapBaseline,
+    bootstrap_baseline: bootstrapBaseline2,
     agents,
     skills,
     current_state: presence.current_state,
@@ -2682,7 +2683,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "useful");
   let overall;
   if (scan === "missing") overall = "initialized";
-  else if (bootstrapBaseline === "incomplete") overall = "bootstrap-incomplete";
+  else if (bootstrapBaseline2 === "incomplete") overall = "bootstrap-incomplete";
   else if (agents === "missing") overall = "agents-missing";
   else if (skills === "missing") overall = "skills-missing";
   else if (understand === "missing") overall = "scanned";
@@ -5553,6 +5554,84 @@ function renderSignalsCompact(signals) {
   return lines.length > 0 ? lines.join("\n") + "\n" : "No signals detected.\n";
 }
 
+// ../cli/src/core/work-item-source.ts
+var VALID_SOURCES = [
+  "manual",
+  "roadmap",
+  "jira",
+  "github",
+  "notion",
+  "xlsx",
+  "csv",
+  "api",
+  "external",
+  "unknown"
+];
+function isValidSource(s) {
+  return VALID_SOURCES.includes(s);
+}
+function parseWorkItemSource(frontmatter) {
+  const raw = frontmatter.source ? String(frontmatter.source) : "";
+  if (raw && isValidSource(raw)) {
+    return {
+      type: raw,
+      id: optStr(frontmatter.source_id),
+      title: optStr(frontmatter.source_title),
+      context: optStr(frontmatter.source_context),
+      provider: optStr(frontmatter.source_provider),
+      url: optStr(frontmatter.source_url),
+      imported_at: optStr(frontmatter.source_imported_at),
+      synced_at: optStr(frontmatter.source_synced_at),
+      inferred: false
+    };
+  }
+  if (raw && !isValidSource(raw)) {
+    return {
+      type: "unknown",
+      id: optStr(frontmatter.source_id),
+      title: optStr(frontmatter.source_title),
+      context: optStr(frontmatter.source_context),
+      provider: optStr(frontmatter.source_provider),
+      url: optStr(frontmatter.source_url),
+      imported_at: optStr(frontmatter.source_imported_at),
+      synced_at: optStr(frontmatter.source_synced_at),
+      inferred: true,
+      reason: `Invalid source value: "${raw}".`
+    };
+  }
+  if (frontmatter.source_work_item_candidate || frontmatter.source_roadmap_initiative) {
+    return {
+      type: "roadmap",
+      id: optStr(frontmatter.source_id) ?? optStr(frontmatter.source_work_item_candidate),
+      title: optStr(frontmatter.source_initiative_title),
+      inferred: true,
+      reason: "Inferred from legacy roadmap fields."
+    };
+  }
+  if (frontmatter.source_id) {
+    return {
+      type: "unknown",
+      id: optStr(frontmatter.source_id),
+      inferred: true,
+      reason: "Has source_id but no source type."
+    };
+  }
+  return {
+    type: "unknown",
+    inferred: true,
+    reason: "No source metadata found."
+  };
+}
+function renderSourceCompact(source) {
+  const parts = [source.type];
+  if (source.id) parts.push(source.id);
+  return parts.join(" \xB7 ");
+}
+function optStr(v) {
+  if (typeof v === "string" && v.trim()) return v.trim();
+  return void 0;
+}
+
 // ../cli/src/core/project-route.ts
 function isUseful(q) {
   return q === "useful";
@@ -5575,6 +5654,14 @@ var scanRepository = {
     return { status: "done", evidence: [".kaddo/scan.json"] };
   }
 };
+var bootstrapBaseline = {
+  id: "bootstrap",
+  label: "Bootstrap knowledge baseline",
+  evaluate: (ctx) => {
+    if (ctx.qBusiness !== "missing" && ctx.qProduct !== "missing") return { status: "done", evidence: ["knowledge/business/business.md", "knowledge/product/product.md"] };
+    return { status: "pending", command: "kaddo bootstrap", reason: "The knowledge baseline is incomplete." };
+  }
+};
 var defineBusiness = {
   id: "define-business",
   label: "Define business context",
@@ -5639,12 +5726,12 @@ var captureTechDecisions = {
 var createWorkSource = {
   id: "create-work-source",
   label: "Create or connect work source",
-  evaluate: (ctx) => ({
-    status: ctx.hasRoadmap || ctx.totalWorkItems > 0 ? "done" : "pending",
-    evidence: ctx.hasRoadmap ? ["knowledge/delivery/roadmap.md"] : void 0,
-    command: ctx.hasRoadmap ? void 0 : "kaddo roadmap",
-    agent: ctx.hasRoadmap ? void 0 : "roadmap-agent"
-  })
+  evaluate: (ctx) => {
+    if (!ctx.hasRoadmap && ctx.totalWorkItems === 0) return { status: "pending", command: "kaddo roadmap", agent: "roadmap-agent" };
+    if (ctx.hasUnknownSources) return { status: "warning", evidence: ["Work Items with unknown source"], reason: "Some Work Items have no source metadata." };
+    const evidence = ctx.hasRoadmap ? ["knowledge/delivery/roadmap.md"] : void 0;
+    return { status: "done", evidence };
+  }
 };
 var materializeWorkItem = {
   id: "materialize-work-item",
@@ -5771,6 +5858,7 @@ var NEW_STEPS = [
 var PRE_AI_STEPS = [
   enableKaddo,
   scanRepository,
+  bootstrapBaseline,
   defineBusiness,
   defineProduct,
   discoverCapabilities,
@@ -5788,6 +5876,7 @@ var PRE_AI_STEPS = [
 var LEGACY_STEPS = [
   enableKaddo,
   scanRepository,
+  bootstrapBaseline,
   identifyLegacyModules,
   { ...discoverCapabilities, label: "Discover critical capabilities" },
   describeArchitecture,
@@ -5861,6 +5950,10 @@ function buildRouteContext(dir) {
     adaptersInstalled: adapters.length,
     hasGuardHistory: exists(join(dir, ".kaddo", "history", "guard-runs.jsonl")),
     hasScanWarnings: hasScan ? loadScanWarnings(dir) : false,
+    hasUnknownSources: wis.some((w) => {
+      const src = parseWorkItemSource(w.rawFrontmatter);
+      return src.type === "unknown" && src.inferred;
+    }),
     nextStepId: mapNextStepId(nextStep.id)
   };
 }
@@ -5875,7 +5968,7 @@ function loadScanWarnings(dir) {
 function mapNextStepId(id) {
   const MAP = {
     init: "enable-kaddo",
-    bootstrap: "define-business",
+    bootstrap: "bootstrap",
     "add-agents": "enable-kaddo",
     "add-skills": "enable-kaddo",
     scan: "scan-repository",
@@ -6044,6 +6137,15 @@ function hasAgents(dir) {
   }
   return hasAgentMd(agentsDir);
 }
+function hasSkills(dir) {
+  const skillsDir = join(dir, ARCH_DIR2, "skills");
+  if (!exists(skillsDir)) return false;
+  try {
+    return readDir(skillsDir).some((e) => e.endsWith(".md") && isFile(join(skillsDir, e)));
+  } catch {
+    return false;
+  }
+}
 function buildProjectExplanation(dir) {
   const config = loadConfig(dir);
   const project = {
@@ -6070,23 +6172,30 @@ function buildProjectExplanation(dir) {
     hasInventory: exists(join(dir, ARCH_DIR2, "inventory.md")),
     hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
     hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
+    hasBusiness: exists(join(dir, "knowledge/business/business.md")),
+    hasProduct: exists(join(dir, "knowledge/product/product.md")),
     hasCapabilities: layerStatus("Product") !== "Missing",
     hasArchitecture: layerStatus("Tech") !== "Missing",
     hasRoadmap: layerStatus("Delivery") !== "Missing",
-    hasAgents: hasAgents(dir)
+    hasAgents: hasAgents(dir),
+    hasSkills: hasSkills(dir)
   };
   const workItemArtifacts = discoverWorkItems(dir);
-  const items = workItemArtifacts.map((a) => ({
-    id: a.id || a.title,
-    title: a.title,
-    type: a.type,
-    status: a.status,
-    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
-    initiative: a.initiative,
-    knowledgeLevel: a.knowledgeLevel,
-    hasOwnership: a.codeGlobs.length > 0,
-    domains: a.domains
-  }));
+  const items = workItemArtifacts.map((a) => {
+    const src = parseWorkItemSource(a.rawFrontmatter);
+    return {
+      id: a.id || a.title,
+      title: a.title,
+      type: a.type,
+      status: a.status,
+      lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
+      initiative: a.initiative,
+      knowledgeLevel: a.knowledgeLevel,
+      hasOwnership: a.codeGlobs.length > 0,
+      domains: a.domains,
+      source: { type: src.type, ...src.id ? { id: src.id } : {}, inferred: src.inferred }
+    };
+  });
   const byState = lifecycleCounts(items.map((i) => i.lifecycle));
   const byType = {};
   for (const i of items) {
@@ -6134,33 +6243,42 @@ function buildProjectExplanation(dir) {
   if (!knowledge.hasAgents) missingKnowledge.push("Agents (knowledge/agents/)");
   if (items.length === 0) missingKnowledge.push("Work items (knowledge/delivery/work-items/)");
   const suggestedNextSteps = [];
-  if (!knowledge.hasScan) {
-    suggestedNextSteps.push("Run `kaddo scan` to detect the technical stack.");
-  } else if (!knowledge.hasContextPack) {
-    suggestedNextSteps.push("Run `kaddo context` to prepare an LLM context pack.");
-  }
-  if (!knowledge.hasAgents) {
-    suggestedNextSteps.push("Run `kaddo add agents` to install knowledge agents.");
-  }
-  if (!knowledge.hasCapabilities) {
-    suggestedNextSteps.push("Use capability-agent to generate knowledge/product/capabilities.md.");
-  }
-  if (!knowledge.hasArchitecture) {
-    suggestedNextSteps.push("Use architecture-agent to generate knowledge/tech/current-state.md.");
-  }
-  if (!knowledge.hasRoadmap) {
-    suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
-  } else if (roadmap.remaining > 0) {
-    suggestedNextSteps.push(
-      `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
-    );
-  }
-  if (items.length === 0 && !roadmap.present) {
-    suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
-  } else if (ownership.workItemsMissingOwnership > 0) {
-    suggestedNextSteps.push(
-      "Run `kaddo owners suggest` for Work Items without code ownership."
-    );
+  const baselineIncomplete = !knowledge.hasBusiness || !knowledge.hasProduct;
+  if (baselineIncomplete) {
+    suggestedNextSteps.push("Run `kaddo bootstrap` to create the project knowledge baseline.");
+    if (!knowledge.hasAgents) suggestedNextSteps.push("Then run `kaddo add agents`.");
+    if (!knowledge.hasSkills) suggestedNextSteps.push("Then run `kaddo add skills`.");
+    suggestedNextSteps.push("Then run `kaddo context`.");
+    suggestedNextSteps.push("Then run `kaddo understand`.");
+  } else {
+    if (!knowledge.hasScan) {
+      suggestedNextSteps.push("Run `kaddo scan` to detect the technical stack.");
+    } else if (!knowledge.hasContextPack) {
+      suggestedNextSteps.push("Run `kaddo context` to prepare an LLM context pack.");
+    }
+    if (!knowledge.hasAgents) {
+      suggestedNextSteps.push("Run `kaddo add agents` to install knowledge agents.");
+    }
+    if (!knowledge.hasCapabilities) {
+      suggestedNextSteps.push("Use capability-agent to generate knowledge/product/capabilities.md.");
+    }
+    if (!knowledge.hasArchitecture) {
+      suggestedNextSteps.push("Use architecture-agent to generate knowledge/tech/current-state.md.");
+    }
+    if (!knowledge.hasRoadmap) {
+      suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
+    } else if (roadmap.remaining > 0) {
+      suggestedNextSteps.push(
+        `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
+      );
+    }
+    if (items.length === 0 && !roadmap.present) {
+      suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
+    } else if (ownership.workItemsMissingOwnership > 0) {
+      suggestedNextSteps.push(
+        "Run `kaddo owners suggest` for Work Items without code ownership."
+      );
+    }
   }
   const readiness = buildReadinessReport(dir);
   return {
@@ -6283,6 +6401,17 @@ function renderExplanationHuman(exp) {
       for (const [t, n] of typeEntries) lines.push(`- ${typeLabel(t)}: ${n}`);
       lines.push("");
     }
+    const sourceCounts = {};
+    for (const i of exp.workItems.items) {
+      const t = i.source?.type ?? "unknown";
+      sourceCounts[t] = (sourceCounts[t] ?? 0) + 1;
+    }
+    const sourceEntries = Object.entries(sourceCounts).filter(([, n]) => n > 0);
+    if (sourceEntries.length > 0) {
+      lines.push("## Work Item Sources");
+      for (const [t, n] of sourceEntries) lines.push(`- ${t.charAt(0).toUpperCase() + t.slice(1)}: ${n}`);
+      lines.push("");
+    }
     const grouped = exp.workItems.initiatives.filter(
       (g) => LIFECYCLE_STATES.some((s2) => g.states[s2] > 0)
     );
@@ -7411,6 +7540,20 @@ function serializeDriftJson(r) {
 
 // src/workitems.ts
 import matter8 from "gray-matter";
+var VALID_SOURCES2 = /* @__PURE__ */ new Set(["manual", "roadmap", "jira", "github", "notion", "xlsx", "csv", "api", "external", "unknown"]);
+function optStr2(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : void 0;
+}
+function parseSource(data) {
+  const raw = data.source ? String(data.source) : "";
+  if (raw && VALID_SOURCES2.has(raw)) {
+    return { type: raw, id: optStr2(data.source_id), title: optStr2(data.source_title), url: optStr2(data.source_url), provider: optStr2(data.source_provider), inferred: false };
+  }
+  if (data.source_work_item_candidate || data.source_roadmap_initiative) {
+    return { type: "roadmap", id: optStr2(data.source_id) ?? optStr2(data.source_work_item_candidate), title: optStr2(data.source_initiative_title), inferred: true };
+  }
+  return { type: "unknown", inferred: true };
+}
 var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
 function strArray(v) {
   return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
@@ -7454,7 +7597,8 @@ function listWorkItems(root) {
       code: strArray(data.code),
       capabilities: strArray(data.capabilities),
       decisions: strArray(data.decisions),
-      capsules: strArray(data.capsules)
+      capsules: strArray(data.capsules),
+      source: parseSource(data)
     });
   }
   return items.sort((a, b) => a.id.localeCompare(b.id));
@@ -7957,7 +8101,8 @@ function toContextWorkItem(a) {
     status: a.status,
     lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
     knowledgeLevel: a.knowledgeLevel,
-    domains: a.domains
+    domains: a.domains,
+    source: parseWorkItemSource(a.rawFrontmatter)
   };
 }
 function toContextArtifact(a) {
@@ -8298,7 +8443,10 @@ function renderContextPack(pack) {
       const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
       const status = wi.lifecycle ? ` (${wi.lifecycle})` : wi.status ? ` (${wi.status})` : "";
       const domains = wi.domains.length > 0 ? ` \xB7 domains: ${wi.domains.join(", ")}` : "";
-      return `- ${wi.id || wi.title} [${wi.type}]${level}${status} \u2014 ${wi.title}${domains}`;
+      const line = `- ${wi.id || wi.title} [${wi.type}]${level}${status} \u2014 ${wi.title}${domains}`;
+      const src = wi.source && wi.source.type !== "unknown" ? `
+  - Source: ${renderSourceCompact(wi.source)}` : "";
+      return `${line}${src}`;
     });
     parts.push(lines.join("\n") + "\n");
   } else {
@@ -8390,19 +8538,35 @@ function renderContextPack(pack) {
     parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
     parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
   }
+  const isBootstrapIncomplete = rec.id === "bootstrap";
   parts.push("## Missing Context\n");
-  if (missing.length > 0) {
+  if (isBootstrapIncomplete) {
+    const baselineMissing = [
+      "- Bootstrap baseline is incomplete.",
+      ...!pack.knowledgeQuality.business || pack.knowledgeQuality.business.status === "Missing" ? ["- Missing business knowledge."] : [],
+      ...!pack.knowledgeQuality.product || pack.knowledgeQuality.product.status === "Missing" ? ["- Missing product knowledge."] : []
+    ];
+    if (missing.length > 0) {
+      baselineMissing.push(...missing.filter((m) => !baselineMissing.some((b) => b.includes(m))));
+    }
+    parts.push(baselineMissing.join("\n") + "\n");
+  } else if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
   } else {
     parts.push("_None \u2014 all expected context is present._\n");
   }
   parts.push("## Recommended Agent Handoff\n");
-  parts.push(`Recommended next for the **${pack.phase.phase}** phase:
+  if (isBootstrapIncomplete) {
+    parts.push("No agent handoff yet.\n");
+    parts.push("Run `kaddo bootstrap` first to create the baseline files.\n");
+  } else {
+    parts.push(`Recommended next for the **${pack.phase.phase}** phase:
 `);
-  parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
-  if (handoff.nextSteps.length > 0) {
-    parts.push("Next step:\n");
-    parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
+    parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
+    if (handoff.nextSteps.length > 0) {
+      parts.push("Next step:\n");
+      parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
+    }
   }
   parts.push("## Instructions for the LLM\n");
   parts.push(handoff.instructions.map((i) => `- ${i}`).join("\n") + "\n");
@@ -8515,7 +8679,12 @@ function renderUnderstand(plan) {
     parts.push("## Project Route\n");
     parts.push(renderRouteCompact(plan.projectRoute));
   }
-  if (steps.length > 0) {
+  const isBootstrap = rec && rec.id === "bootstrap";
+  if (isBootstrap) {
+    parts.push("## Agent Handoff\n");
+    parts.push("Agent handoff is not ready yet.\n");
+    parts.push("Run `kaddo bootstrap` first.\n");
+  } else if (steps.length > 0) {
     parts.push("## Recommended Agent Flow\n");
     parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
 `);
@@ -8556,7 +8725,11 @@ function renderUnderstand(plan) {
   if (plan.activeWorkItems && plan.activeWorkItems.length > 0) {
     parts.push("## Active Work Items\n");
     parts.push(
-      plan.activeWorkItems.map((w) => `- ${w.id} [${w.type}] ${w.lifecycle} \u2014 ${w.title}`).join("\n") + "\n"
+      plan.activeWorkItems.map((w) => {
+        const src = w.source && w.source.type !== "unknown" ? `
+  - Source: ${w.source.type}${w.source.id ? ` \xB7 ${w.source.id}` : ""}` : "";
+        return `- ${w.id} [${w.type}] ${w.lifecycle} \u2014 ${w.title}${src}`;
+      }).join("\n") + "\n"
     );
   }
   parts.push("## Context Pack\n");

package/package.json

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