@kaddo/mcp 3.52.0 → 3.54.0

package/dist/index.js

@@ -274,7 +274,7 @@ function join(...parts) {
 }
 
 // ../cli/src/core/impact-report.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
@@ -2496,9 +2496,6 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (!exists(join(dir, ".kaddo", "context-pack.md"))) {
     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 (!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." };
-  }
   const discovery = state === "pre-ai" || state === "legacy";
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
@@ -2538,6 +2535,9 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     const agent = ctx.agents.includes("codebase-agent") ? "codebase-agent" : "architecture-agent";
     return refine("refine-codebase", agent, CB, qCodebase);
   }
+  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." };
+  }
   const oq = buildOpenQuestionsReport(dir, now);
   if (oq.summary.blocking_open > 0) {
     return { id: "questions", phase: "Knowledge Refinement", label: "Run `kaddo questions` to see source locations and resolution guidance, then resolve, assume or defer the blocking open questions.", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
@@ -3445,16 +3445,49 @@ function renderSkillsSection(agent) {
     ""
   ].join("\n");
 }
+var KNOWLEDGE_REFINING_AGENTS = {
+  "business-agent": "business-agent",
+  "capability-agent": "capability-agent",
+  "bootstrap-agent": "bootstrap-agent",
+  "codebase-agent": "codebase-agent",
+  "architecture-agent": "architecture-agent",
+  "roadmap-agent": "roadmap-agent",
+  "legacy-agent": "legacy-agent",
+  "work-item-agent": "work-item-agent",
+  "backlog-agent": "backlog-agent",
+  "adr-agent": "adr-agent",
+  "implementation-agent": "implementation-agent"
+};
+function renderFrontmatterRules(agent) {
+  if (!KNOWLEDGE_REFINING_AGENTS[agent]) return "";
+  return [
+    "## Frontmatter Rules",
+    "",
+    "When rewriting an existing Kaddo knowledge file:",
+    "",
+    "- Preserve the existing YAML frontmatter.",
+    "- Do not remove `type`, `generated_by`, or `template_version`.",
+    "- If the document is no longer a placeholder, set `project_state: ai-assisted`.",
+    `- Add or update \`refined_by: ${agent}\`.`,
+    "- Preserve unknown frontmatter keys \u2014 do not strip fields you do not recognize.",
+    "- Only rewrite the markdown body unless metadata changes are explicitly required by these rules.",
+    "- Preserve structural sections like `## Open Questions` \u2014 leave them empty rather than removing them.",
+    ""
+  ].join("\n");
+}
 function withResponsibilityTrace(fileName, content) {
   const agent = fileName.replace(/\.md$/, "");
   if (!RESPONSIBILITY_MATRIX[agent]) return content;
   const skills = renderSkillsSection(agent);
   const skillsBlock = skills ? `${skills}
+` : "";
+  const frontmatter = renderFrontmatterRules(agent);
+  const frontmatterBlock = frontmatter ? `${frontmatter}
 ` : "";
   return `${content.trimEnd()}
 
 ${renderLanguageRule()}
-${renderAgentBoundaries(agent)}
+${frontmatterBlock}${renderAgentBoundaries(agent)}
 ${skillsBlock}${renderAgentTrace(agent)}`;
 }
 
@@ -5986,7 +6019,6 @@ function mapNextStepId(id) {
     "add-skills": "enable-kaddo",
     scan: "scan-repository",
     context: "scan-repository",
-    understand: "scan-repository",
     "refine-business": "define-business",
     "refine-product": "define-product",
     "refine-capabilities": "discover-capabilities",
@@ -6074,6 +6106,54 @@ function renderRouteCompact(route) {
   return lines.join("\n");
 }
 
+// ../cli/src/core/metadata-health.ts
+import matter7 from "gray-matter";
+var KNOWLEDGE_FILES2 = [
+  "knowledge/business/business.md",
+  "knowledge/product/product.md",
+  "knowledge/product/capabilities.md",
+  "knowledge/tech/codebase.md",
+  "knowledge/tech/current-state.md",
+  "knowledge/delivery/roadmap.md"
+];
+var REQUIRED_FIELDS = ["type", "generated_by", "template_version"];
+function analyzeMetadataHealth(dir) {
+  const findings = [];
+  let healthy = 0;
+  let drifted = 0;
+  for (const rel of KNOWLEDGE_FILES2) {
+    const p = join(dir, rel);
+    if (!exists(p)) continue;
+    let data;
+    try {
+      const raw = readFile(p);
+      data = matter7(raw).data;
+    } catch {
+      continue;
+    }
+    if (Object.keys(data).length === 0) continue;
+    let fileDrifted = false;
+    for (const field of REQUIRED_FIELDS) {
+      if (data[field] === void 0 || data[field] === null || data[field] === "") {
+        findings.push({ file: rel, field, issue: "missing", detail: `Missing \`${field}\` in frontmatter.` });
+        fileDrifted = true;
+      }
+    }
+    if (data.refined_by && data.project_state && data.project_state !== "ai-assisted") {
+      findings.push({
+        file: rel,
+        field: "project_state",
+        issue: "inconsistent",
+        detail: `File has \`refined_by: ${data.refined_by}\` but \`project_state\` is \`${data.project_state}\`, expected \`ai-assisted\`.`
+      });
+      fileDrifted = true;
+    }
+    if (fileDrifted) drifted++;
+    else healthy++;
+  }
+  return { findings, healthy, drifted };
+}
+
 // ../cli/src/core/project-explain.ts
 var ARCH_DIR2 = "knowledge";
 function normalizeTitle(t) {
@@ -6336,7 +6416,8 @@ function buildProjectExplanation(dir) {
     installedAssets: installedAssetsSummary(dir),
     roadmapQuality: buildRoadmapQuality(dir),
     projectRoute: buildProjectRoute(dir),
-    scanSignals: loadScanSignals(dir)
+    scanSignals: loadScanSignals(dir),
+    metadataHealth: analyzeMetadataHealth(dir)
   };
 }
 function stateLabel(state) {
@@ -6645,6 +6726,13 @@ function renderExplanationHuman(exp) {
     }
     lines.push("");
   }
+  if (exp.metadataHealth.findings.length > 0) {
+    lines.push("## Metadata Health");
+    for (const f of exp.metadataHealth.findings) {
+      lines.push(`- \`${f.file}\`: ${f.detail}`);
+    }
+    lines.push("");
+  }
   return lines.join("\n").trimEnd() + "\n";
 }
 function renderExplanationAgent(exp) {
@@ -6844,7 +6932,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter7(readFile(wi.filePath)).content;
+      const body = matter8(readFile(wi.filePath)).content;
       if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
       else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
       if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -7557,7 +7645,7 @@ function serializeDriftJson(r) {
 }
 
 // src/workitems.ts
-import matter8 from "gray-matter";
+import matter9 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;
@@ -7598,7 +7686,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter8(raw);
+      parsed = matter9(raw);
     } catch {
       continue;
     }
@@ -8061,7 +8149,7 @@ function listGraphHints(root, filter = {}) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR3 = "knowledge";
 function readScanJson(dir) {
@@ -8074,7 +8162,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph3(markdown) {
-  const body = matter9(markdown).content.trim();
+  const body = matter10(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -8289,6 +8377,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     skills: discoverInstalledSkills(dir).map((s) => s.id),
     scanSignals: scanJson?.signals ?? null,
     projectRoute: buildProjectRoute(dir),
+    metadataHealth: analyzeMetadataHealth(dir),
     mappedModules,
     missing,
     // VS-052/VS-073.2: the handoff is driven by the unified next step, so the pack never contradicts
@@ -8577,6 +8666,13 @@ function renderContextPack(pack) {
   } else {
     parts.push("_None \u2014 all expected context is present._\n");
   }
+  if (pack.metadataHealth.findings.length > 0) {
+    parts.push("\n### Metadata Health\n");
+    for (const f of pack.metadataHealth.findings) {
+      parts.push(`- \`${f.file}\`: ${f.detail}
+`);
+    }
+  }
   parts.push("## Recommended Agent Handoff\n");
   if (isBootstrapIncomplete) {
     parts.push("No agent handoff yet.\n");
@@ -8884,6 +8980,13 @@ function renderUnderstand(plan) {
   } else {
     parts.push("Re-run `kaddo understand` any time to see this plan again.\n");
   }
+  if (plan.metadataHealth && plan.metadataHealth.findings.length > 0) {
+    parts.push("## Metadata Health\n");
+    for (const f of plan.metadataHealth.findings) {
+      parts.push(`- \`${f.file}\`: ${f.detail}
+`);
+    }
+  }
   return parts.join("\n");
 }
 

package/package.json

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