@kaddo/cli 3.36.0 → 3.37.0

package/README.md

@@ -532,6 +532,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.34 | Pre-AI onboarding: `kaddo onboarding` (alias `onboard`) / `kaddo report onboarding` — read-only diagnosis of an existing project's readiness (scan/understand/knowledge/questions/roadmap/work-items/adapters) with a single recommended next step; `--json` |
 | v3.35 | Folded onboarding into `kaddo explain`: removed `kaddo onboarding`/`onboard`/`report onboarding`; project readiness + single recommended next step now live in `kaddo explain` (human `## Project Readiness` + `readiness` in agent JSON) |
 | v3.36 | State-aware bootstrap: `kaddo bootstrap` creates the full knowledge baseline for any `project.state` (new/pre-ai/legacy) with state-specific templates — no more new-only warning; idempotent, never overwrites, ensures `tech/decisions/` and `delivery/work-items/` |
+| v3.37 | Placeholder-aware readiness: knowledge files are classified missing/placeholder/weak/useful; a bootstrap file isn't treated as ready knowledge. Layers downgrade to Placeholder/Weak, a new Knowledge Refinement phase recommends the right agent, and `create --from roadmap` is never suggested with 0 candidates |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -6041,14 +6041,23 @@ import { parse as parseYaml9 } from "yaml";
 function layer(layers, name) {
   return layers.find((l) => l.layer === name)?.status ?? "Missing";
 }
+var NOT_READY_LAYER = ["Missing", "Placeholder", "Weak"];
 function baseComplete(layers) {
   return layer(layers, "Business") !== "Missing" && layer(layers, "Product") !== "Missing" && layer(layers, "Tech") !== "Missing";
 }
+function baseUseful(layers) {
+  return ["Business", "Product", "Tech"].every((n) => !NOT_READY_LAYER.includes(layer(layers, n)));
+}
+function roadmapHasCandidates(roadmap) {
+  return roadmap.candidates > 0 || roadmap.remaining > 0;
+}
 function determinePhase(input) {
   const { roadmap, workItems } = input;
   const active = workItems.byState.draft + workItems.byState.ready + workItems.byState["in-progress"] + workItems.byState.blocked;
   if (!baseComplete(input.layers)) return "Discovery";
+  if (!baseUseful(input.layers)) return "Knowledge Refinement";
   if (!roadmap.present) return "Planning";
+  if (!roadmapHasCandidates(roadmap) && workItems.total === 0) return "Planning";
   if (workItems.total === 0) return "Delivery Preparation";
   if (active > 0) return "Active Delivery";
   return "Maintenance";
@@ -6078,6 +6087,14 @@ function firstMissingLayerAgent(layers) {
     return { agent: "capability-agent", step: "Use capability-agent to create knowledge/product/capabilities.md" };
   return { agent: "architecture-agent", step: "Use architecture-agent to create knowledge/tech/current-state.md" };
 }
+function firstUnrefinedLayerAgent(layers) {
+  const isThin = (n) => NOT_READY_LAYER.includes(layer(layers, n));
+  if (isThin("Business"))
+    return { agent: "business-agent", step: "Use business-agent to complete knowledge/business/business.md" };
+  if (isThin("Product"))
+    return { agent: "capability-agent", step: "Use capability-agent to complete knowledge/product/capabilities.md" };
+  return { agent: "architecture-agent", step: "Use architecture-agent to complete knowledge/tech/current-state.md" };
+}
 function assessPhase(input) {
   const phase = determinePhase(input);
   const reasons = buildReasons(input);
@@ -6095,6 +6112,17 @@ function assessPhase(input) {
       llmInstructions = [`Use the ${m.agent} to fill the missing base knowledge.`, "Do not write code."];
       break;
     }
+    case "Knowledge Refinement": {
+      const m = firstUnrefinedLayerAgent(input.layers);
+      recommendedAgents2 = [m.agent];
+      nextStep = m.step;
+      llmInstructions = [
+        "The baseline files exist but still look like bootstrap placeholders.",
+        `Use the ${m.agent} to replace the placeholders with real, project-specific knowledge.`,
+        "Do not write code."
+      ];
+      break;
+    }
     case "Planning": {
       recommendedAgents2 = ["roadmap-agent"];
       nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
@@ -6957,9 +6985,97 @@ function statusFor(layer2, a) {
   return "Missing";
 }
 
+// src/core/artifact-quality.ts
+function isPlaceholderLine(line) {
+  const t = line.trim();
+  if (/^_.+_$/.test(t)) return true;
+  if (/^[-*]\s+(\[[^\]]+\]\s*)?_.+_$/.test(t)) return true;
+  if (/^[-*]\s+\[[^\]]+\]\s*$/.test(t)) return true;
+  if (/^_(?:Describe|List|Document|What|Which|Who|Use|To be defined|No production code)\b/i.test(t)) return true;
+  return false;
+}
+function isStructuralLine(line, inFrontMatter) {
+  const t = line.trim();
+  if (inFrontMatter) return true;
+  if (t === "") return true;
+  if (/^#{1,6}\s/.test(t)) return true;
+  if (/^<!--/.test(t)) return true;
+  if (/^>/.test(t)) return true;
+  return false;
+}
+function analyzeContent(md) {
+  const lines = md.split(/\r?\n/);
+  let inFrontMatter = false;
+  let seenFmFence = 0;
+  let currentSectionHasUseful = false;
+  const sectionsWithUseful = /* @__PURE__ */ new Set();
+  let sectionIndex = 0;
+  const contentLines = [];
+  const usefulLines = [];
+  for (const raw of lines) {
+    const t = raw.trim();
+    if (t === "---" && seenFmFence < 2) {
+      seenFmFence += 1;
+      inFrontMatter = seenFmFence === 1;
+      continue;
+    }
+    if (seenFmFence === 1) continue;
+    if (/^#{1,6}\s/.test(t)) {
+      sectionIndex += 1;
+      currentSectionHasUseful = false;
+      continue;
+    }
+    if (isStructuralLine(raw, false)) continue;
+    contentLines.push(t);
+    if (!isPlaceholderLine(raw)) {
+      usefulLines.push(t);
+      if (!currentSectionHasUseful) {
+        currentSectionHasUseful = true;
+        sectionsWithUseful.add(sectionIndex);
+      }
+    }
+  }
+  if (usefulLines.length === 0) return "placeholder";
+  const usefulWordCount = usefulLines.join(" ").split(/\s+/).filter(Boolean).length;
+  const placeholderRatio = contentLines.length > 0 ? (contentLines.length - usefulLines.length) / contentLines.length : 1;
+  if (usefulWordCount >= 80 && placeholderRatio < 0.25 && sectionsWithUseful.size >= 2) return "useful";
+  return "weak";
+}
+function analyzeKnowledgeArtifact(dir, rel) {
+  const p2 = join(dir, rel);
+  if (!exists(p2)) return "missing";
+  try {
+    return analyzeContent(readFile(p2));
+  } catch {
+    return "missing";
+  }
+}
+
 // src/core/layers.ts
+var LAYER_BASELINE = {
+  Business: ["knowledge/business/business.md"],
+  Product: ["knowledge/product/product.md", "knowledge/product/capabilities.md"],
+  Tech: ["knowledge/tech/codebase.md", "knowledge/tech/current-state.md"],
+  Delivery: ["knowledge/delivery/roadmap.md"]
+};
+function layerQuality(dir, layer2) {
+  const order = ["missing", "placeholder", "weak", "useful"];
+  let worst = null;
+  for (const rel of LAYER_BASELINE[layer2]) {
+    const q = analyzeKnowledgeArtifact(dir, rel);
+    if (q === "missing") continue;
+    if (worst === null || order.indexOf(q) < order.indexOf(worst)) worst = q;
+  }
+  return worst;
+}
 function knowledgeLayers(dir) {
-  return discoverLayers(dir);
+  return discoverLayers(dir).map((l) => {
+    if (l.status !== "Consolidated" && l.status !== "Structured") return l;
+    const q = layerQuality(dir, l.layer);
+    if (q === "placeholder") return { ...l, status: "Placeholder" };
+    if (q === "weak") return { ...l, status: "Weak" };
+    return l;
+  });
 }
 function renderLayersMarkdown(layers) {
   const lines = [];
@@ -7631,24 +7747,12 @@ function buildSharedFileStatuses(statuses) {
 
 // src/core/readiness.ts
 var KNOWLEDGE_FILES = [
-  { key: "current_state", path: "knowledge/tech/current-state.md", label: "knowledge/tech/current-state.md" },
-  { key: "codebase", path: "knowledge/tech/codebase.md", label: "knowledge/tech/codebase.md" },
-  { key: "capabilities", path: "knowledge/product/capabilities.md", label: "knowledge/product/capabilities.md" },
-  { key: "product", path: "knowledge/product/product.md", label: "knowledge/product/product.md" },
-  { key: "business", path: "knowledge/business/business.md", label: "knowledge/business/business.md" }
+  { 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" },
+  { key: "product", path: "knowledge/product/product.md", label: "knowledge/product/product.md", agent: "product-agent" },
+  { key: "business", path: "knowledge/business/business.md", label: "knowledge/business/business.md", agent: "business-agent" }
 ];
-function knowledgePresence(dir, rel) {
-  const p2 = join(dir, rel);
-  if (!exists(p2)) return "missing";
-  let md;
-  try {
-    md = readFile(p2);
-  } catch {
-    return "missing";
-  }
-  const body = md.replace(/^---[\s\S]*?---/m, "").split(/\r?\n/).filter((l) => !/^\s*#{1,6}\s/.test(l) && !/^\s*$/.test(l) && !/^\s*<!--/.test(l)).join(" ").trim();
-  return body.length >= 40 ? "present" : "weak";
-}
 function roadmapSignal(dir) {
   const p2 = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p2)) return "missing";
@@ -7711,7 +7815,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, knowledgePresence(dir, f.path)]));
+  const presence = Object.fromEntries(KNOWLEDGE_FILES.map((f) => [f.key, analyzeKnowledgeArtifact(dir, f.path)]));
   const ctx = buildCodexAdapterContext(dir);
   const agents = ctx.hasAgents ? "present" : "missing";
   const skills = ctx.hasSkills ? "present" : "missing";
@@ -7741,7 +7845,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   };
   let overall;
   let next;
-  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "present");
+  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "useful");
   if (scan2 === "missing") {
     overall = "initialized";
     next = { label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan" };
@@ -7759,7 +7863,7 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
     next = { label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand" };
   } else if (firstWeak) {
     overall = "knowledge-incomplete";
-    next = { label: `Complete \`${firstWeak.label}\` (it is ${presence[firstWeak.key]}).` };
+    next = { label: `Use ${firstWeak.agent} to complete \`${firstWeak.label}\` (it is ${presence[firstWeak.key]}).` };
   } else if (oq.summary.blocking_open > 0) {
     overall = "needs-decisions";
     next = { label: "Resolve, assume or defer the blocking open questions (`kaddo questions`).", command: "kaddo questions" };
@@ -8183,6 +8287,9 @@ function renderExplanationHuman(exp) {
     lines.push(`- understand: ${s.understand}`);
     lines.push(`- agents: ${s.agents}`);
     lines.push(`- skills: ${s.skills}`);
+    lines.push(`- business: ${s.business}`);
+    lines.push(`- product: ${s.product}`);
+    lines.push(`- capabilities: ${s.capabilities}`);
     lines.push(`- current-state: ${s.current_state}`);
     lines.push(`- codebase: ${s.codebase}`);
     lines.push(`- capabilities: ${s.capabilities}`);
@@ -8522,6 +8629,24 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   }
   const mappedModules = loadMappedModules(dir);
   const layers = knowledgeLayers(dir);
+  const qa = (rel) => analyzeKnowledgeArtifact(dir, rel);
+  const qBusiness = qa("knowledge/business/business.md");
+  const qProduct = qa("knowledge/product/product.md");
+  const qCapabilities = qa("knowledge/product/capabilities.md");
+  const qCodebase = qa("knowledge/tech/codebase.md");
+  const qCurrentState = qa("knowledge/tech/current-state.md");
+  const qRoadmap = qa("knowledge/delivery/roadmap.md");
+  const layerStatusOf = (name) => layers.find((l) => l.layer === name)?.status ?? "Missing";
+  const knowledgeQuality = {
+    business: { status: layerStatusOf("Business"), artifacts: { "knowledge/business/business.md": qBusiness } },
+    product: { status: layerStatusOf("Product"), artifacts: { "knowledge/product/product.md": qProduct, "knowledge/product/capabilities.md": qCapabilities } },
+    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 (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((a) => a.isWorkItem);
   const wiWithOwnership = allWorkItems.filter((a) => a.codeGlobs.length > 0).length;
   const phase = assessPhase({
@@ -8572,6 +8697,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       artifacts: allArtifacts.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
     },
     layers,
+    knowledgeQuality,
     roadmap,
     phase,
     deliveryMix,
@@ -11846,6 +11972,8 @@ function fm(type, state) {
   return `---
 type: ${type}
 project_state: ${state}
+generated_by: kaddo-bootstrap
+template_version: 1
 ---
 
 `;

package/package.json

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