@kaddo/cli 3.52.0 → 3.54.0

package/dist/index.js

@@ -2791,16 +2791,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)}`;
 }
 
@@ -6271,6 +6304,54 @@ async function collectWorkspaceChanges(dir, mode = "head", deps = defaultDeps) {
   };
 }
 
+// src/core/metadata-health.ts
+import matter2 from "gray-matter";
+var KNOWLEDGE_FILES = [
+  "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_FILES) {
+    const p2 = join(dir, rel);
+    if (!exists(p2)) continue;
+    let data;
+    try {
+      const raw = readFile(p2);
+      data = matter2(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 };
+}
+
 // src/commands/guard.ts
 import path4 from "path";
 import { parse as parseYaml7 } from "yaml";
@@ -6893,6 +6974,14 @@ async function runGuard(opts = {}) {
     console.log("");
   }
   printPluginSignals(pluginSignals);
+  const mh = analyzeMetadataHealth(dir);
+  if (mh.findings.length > 0) {
+    console.log("Metadata health:");
+    for (const f of mh.findings) {
+      console.log(`  \u26A0 ${f.file}: ${f.detail}`);
+    }
+    console.log("");
+  }
   const ownerMap = loadOwners(dir);
   const matchedDomains = collectMatchedDomains(activeMatches.map((m) => m.artifact.domains));
   const affectedOwners = resolveAffectedOwners(matchedDomains, ownerMap);
@@ -6954,7 +7043,7 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
@@ -7120,7 +7209,7 @@ function assessPhase(input) {
 }
 
 // src/core/capsule.ts
-import matter2 from "gray-matter";
+import matter3 from "gray-matter";
 import { parse as parseYaml8, stringify as stringifyYaml3 } from "yaml";
 var KNOWLEDGE = "knowledge";
 function today() {
@@ -7255,7 +7344,7 @@ function sectionParagraph(md, title) {
   return "";
 }
 function parseCapsule(id, path6, md) {
-  const { data } = matter2(md);
+  const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
   if (updatedAt) {
@@ -7281,7 +7370,7 @@ function slugId(s) {
 function addExternalCapsule(dir, sourceFile) {
   if (!exists(sourceFile)) throw new Error(`Capsule not found: ${sourceFile}`);
   const raw = readFile(sourceFile);
-  const { data } = matter2(raw);
+  const { data } = matter3(raw);
   const isCapsuleType = data.type === "knowledge-capsule";
   const fallbackName = sourceFile.split(/[\\/]/).pop()?.replace(/\.capsule\.md$/, "") ?? "external";
   const id = slugId(String(data.system ?? fallbackName));
@@ -7753,7 +7842,7 @@ function loadGraphHints(dir) {
 }
 
 // src/services/installed-skills.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 var SKILLS_DIR = join("knowledge", "skills");
 function discoverInstalledSkills(dir) {
   const base = join(dir, SKILLS_DIR);
@@ -7763,7 +7852,7 @@ function discoverInstalledSkills(dir) {
     const skillFile = join(base, entry, "skill.md");
     if (!isFile(skillFile)) continue;
     try {
-      const { data } = matter3(readFile(skillFile));
+      const { data } = matter4(readFile(skillFile));
       if (data.type && String(data.type) !== "skill") continue;
       const id = String(data.id ?? entry);
       out.push({
@@ -8857,9 +8946,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`;
@@ -8899,6 +8985,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.` };
@@ -9021,7 +9110,7 @@ function buildSecondaryRecommendations(st) {
 }
 
 // src/core/readiness.ts
-var KNOWLEDGE_FILES = [
+var KNOWLEDGE_FILES2 = [
   { key: "current_state", path: "knowledge/tech/current-state.md", label: "knowledge/tech/current-state.md", agent: "architecture-agent" },
   { key: "codebase", path: "knowledge/tech/codebase.md", label: "knowledge/tech/codebase.md", agent: "codebase-agent" },
   { key: "capabilities", path: "knowledge/product/capabilities.md", label: "knowledge/product/capabilities.md", agent: "capability-agent" },
@@ -9062,7 +9151,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   if (config.project.state === "legacy") return stub("legacy-project", "Use the legacy project flow.");
   const scan2 = exists(join(dir, ".kaddo", "scan.json")) ? "available" : "missing";
   const understand = exists(join(dir, ".kaddo", "understand.md")) ? "available" : "missing";
-  const presence = Object.fromEntries(KNOWLEDGE_FILES.map((f) => [f.key, analyzeKnowledgeArtifact(dir, f.path)]));
+  const presence = Object.fromEntries(KNOWLEDGE_FILES2.map((f) => [f.key, analyzeKnowledgeArtifact(dir, f.path)]));
   const ctx = buildCodexAdapterContext(dir);
   const agents = ctx.hasAgents ? "present" : "missing";
   const skills = ctx.hasSkills ? "present" : "missing";
@@ -9090,7 +9179,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
     resolved_questions: oq.summary.resolution.resolved,
     deferred_questions: oq.summary.resolution.deferred
   };
-  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "useful");
+  const firstWeak = KNOWLEDGE_FILES2.find((f) => presence[f.key] !== "useful");
   let overall;
   if (scan2 === "missing") overall = "initialized";
   else if (bootstrapBaseline2 === "incomplete") overall = "bootstrap-incomplete";
@@ -9113,7 +9202,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/core/assets.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 function canonicalAgents() {
   return AGENT_PROMPTS.map((a) => ({
     name: a.fileName.replace(/\.md$/, ""),
@@ -9126,7 +9215,7 @@ function canonicalSkills() {
 }
 function versionOf(content) {
   try {
-    const v = matter4(content).data.version;
+    const v = matter5(content).data.version;
     return v === void 0 || v === null ? null : String(v);
   } catch {
     return null;
@@ -9679,7 +9768,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",
@@ -10029,7 +10117,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) {
@@ -10338,6 +10427,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) {
@@ -10353,7 +10449,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter5(raw);
+    const { data, content } = matter6(raw);
     return { content, data };
   } catch {
     return null;
@@ -10364,7 +10460,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter5(raw);
+    const { content } = matter6(raw);
     return content.trim();
   } catch {
     return null;
@@ -10533,7 +10629,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -10546,7 +10642,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph2(markdown) {
-  const body = matter6(markdown).content.trim();
+  const body = matter7(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -10761,6 +10857,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
@@ -11049,6 +11146,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");
@@ -11180,7 +11284,8 @@ function enrichUnderstandPlan(plan, opts) {
     activeWorkItems: opts.activeWorkItems,
     recommendedPaths: opts.recommendedPaths,
     recommendedSkillPaths: opts.recommendedSkillPaths,
-    projectRoute: opts.projectRoute
+    projectRoute: opts.projectRoute,
+    metadataHealth: opts.metadataHealth
   };
 }
 
@@ -11408,6 +11513,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");
 }
 function renderUnderstandTerminal(plan) {
@@ -11468,7 +11580,13 @@ function renderUnderstandTerminal(plan) {
       }
     }
   }
-  lines.push("");
+  if (plan.metadataHealth && plan.metadataHealth.findings.length > 0) {
+    lines.push("Metadata health:");
+    for (const f of plan.metadataHealth.findings) {
+      lines.push(`  \u26A0 ${f.file}: ${f.detail}`);
+    }
+    lines.push("");
+  }
   lines.push("Kaddo does not call an LLM. You stay in control of the interpretation.");
   lines.push("");
   return lines.join("\n");
@@ -11698,7 +11816,8 @@ function runUnderstand() {
     recommendedPaths,
     recommendedSkillPaths,
     language: languageLabel(projectLanguage(config)),
-    projectRoute: buildProjectRoute(dir)
+    projectRoute: buildProjectRoute(dir),
+    metadataHealth: analyzeMetadataHealth(dir)
   });
   writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(enrichedPlan));
   log2.success("Wrote .kaddo/understand.md");
@@ -11988,7 +12107,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -12000,7 +12119,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter7(raw);
+  const { data, content } = matter8(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -12025,7 +12144,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter7.stringify(updatedContent, data);
+  const newRaw = matter8.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -12275,7 +12394,7 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
 function normalizeGlob(input) {
   let g = input.trim().replace(/\\/g, "/");
@@ -12397,11 +12516,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter8(raw);
+  const parsed = matter9(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter8.stringify(parsed.content, data);
+  return matter9.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -15013,7 +15132,7 @@ function runGraphExport(opts = {}) {
 }
 
 // src/core/impact-report.ts
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 function isBroadGlob(glob) {
   if (!glob.endsWith("/**")) return false;
   const prefix = glob.slice(0, -3);
@@ -15082,7 +15201,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter9(readFile(wi.filePath)).content;
+      const body = matter10(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++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.52.0",
+  "version": "3.54.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {