@kaddo/cli 3.36.0 → 3.37.1

package/README.md

@@ -532,6 +532,8 @@ 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 |
+| v3.37.1 | Unified next-step: one shared resolver (`core/next-step.ts`) powers `context`, `understand` and `explain` (Phase + Readiness) so they never diverge; agent JSON exposes `nextStepRecommendation`. Fixes duplicate `capabilities` line in explain |
 
 **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 = [];
@@ -7629,26 +7745,7 @@ 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" }
-];
-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";
-}
+// src/core/next-step.ts
 function roadmapSignal(dir) {
   const p2 = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p2)) return "missing";
@@ -7679,8 +7776,91 @@ function installedAdapters(dir) {
     (s) => s.state === "injected" || s.state === "legacy-injected" || s.state === "full-generated" && (s.originAdapter === s.id || s.originAdapter === null)
   ).map((s) => s.id);
 }
+var B = "knowledge/business/business.md";
+var P = "knowledge/product/product.md";
+var CAP = "knowledge/product/capabilities.md";
+var CS = "knowledge/tech/current-state.md";
+var CB = "knowledge/tech/codebase.md";
+function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
+  const config = loadConfig(dir);
+  if (!config) {
+    return { id: "init", phase: "Setup", label: "Run `kaddo init` to initialize Kaddo.", command: "kaddo init", reason: "Kaddo is not initialized in this project." };
+  }
+  const state = config.project.state;
+  const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
+  const qBusiness = q(B), qProduct = q(P), qCap = q(CAP), qCurrentState = q(CS), qCodebase = q(CB);
+  if (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." };
+  }
+  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." };
+  }
+  if (!ctx.hasSkills) {
+    return { id: "add-skills", phase: "Setup", label: "Run `kaddo add skills` to install reusable Kaddo skills.", command: "kaddo add skills", reason: "No Kaddo skills are installed yet." };
+  }
+  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." };
+  }
+  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 refine = (id, agent, target, quality) => ({
+    id,
+    phase: "Knowledge Refinement",
+    label: `Use ${agent} to complete \`${target}\`.`,
+    agent,
+    target,
+    reason: `${target} is ${quality === "missing" ? "missing" : "still a bootstrap placeholder or too thin"}.`,
+    instructions: [
+      "The baseline file exists but does not yet hold real, project-specific knowledge.",
+      `Use the ${agent} to replace the placeholders with real knowledge.`,
+      "Do not write code."
+    ]
+  });
+  if (qBusiness !== "useful") return refine("refine-business", "business-agent", B, qBusiness);
+  if (qProduct !== "useful" || qCap !== "useful") {
+    const target = qCap !== "useful" ? CAP : P;
+    return refine("refine-product", "capability-agent", target, qCap !== "useful" ? qCap : qProduct);
+  }
+  if (qCurrentState !== "useful") return refine("refine-current-state", "architecture-agent", CS, qCurrentState);
+  if (qCodebase !== "useful") {
+    const agent = ctx.agents.includes("codebase-agent") ? "codebase-agent" : "architecture-agent";
+    return refine("refine-codebase", agent, CB, qCodebase);
+  }
+  const oq = buildOpenQuestionsReport(dir, now);
+  if (oq.summary.blocking_open > 0) {
+    return { id: "questions", phase: "Knowledge Refinement", label: "Resolve, assume or defer the blocking open questions (`kaddo questions`).", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
+  }
+  const roadmap = roadmapSignal(dir);
+  if (roadmap !== "has-candidates") {
+    return { id: "roadmap", phase: "Planning", label: "Use roadmap-agent to define roadmap candidates (`kaddo roadmap`).", command: "kaddo roadmap", agent: "roadmap-agent", target: "knowledge/delivery/roadmap.md", reason: "The roadmap has no candidates yet." };
+  }
+  const wi = workItemsSignal(dir);
+  if (wi === "none" || wi === "none-ready") {
+    return { id: "create-work-item", phase: "Delivery Preparation", label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap", reason: "The roadmap has candidates but no Work Item is ready." };
+  }
+  const adapters = installedAdapters(dir);
+  if (adapters.length === 0) {
+    return { id: "install-adapter", phase: "Active Delivery", label: "Run `kaddo adapters list` and install the adapter for your preferred agent.", command: "kaddo adapters list", reason: "A Work Item is ready but no adapter is installed." };
+  }
+  return { id: "implement", phase: "Active Delivery", label: "Implement the ready Work Item and run `kaddo guard`.", reason: "A Work Item is ready and an adapter is installed." };
+}
+
+// src/core/readiness.ts
+var KNOWLEDGE_FILES = [
+  { 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 buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   const config = loadConfig(dir);
+  const rec = resolveNextStep(dir, now);
   const stub = (overall2, label, command) => ({
     project_name: config?.project.name ?? "unknown",
     project_type: config?.project.state ?? "unknown",
@@ -7704,14 +7884,15 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
       resolved_questions: 0,
       deferred_questions: 0
     },
-    recommended_next_step: { label, ...command ? { command } : {} }
+    recommended_next_step: { label, ...command ? { command } : {} },
+    nextStepRecommendation: rec
   });
-  if (!config) return stub("not-initialized", "Run `kaddo init` to initialize Kaddo.", "kaddo init");
+  if (!config) return stub("not-initialized", rec.label, rec.command);
   if (config.project.state === "new") return stub("not-applicable", "This project uses the standard new-project Kaddo flow.");
   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";
@@ -7739,41 +7920,26 @@ 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");
   let overall;
-  let next;
-  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "present");
-  if (scan2 === "missing") {
-    overall = "initialized";
-    next = { label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan" };
-  } else if (bootstrapBaseline === "incomplete") {
-    overall = "bootstrap-incomplete";
-    next = { label: "Run `kaddo bootstrap` to create the project knowledge baseline.", command: "kaddo bootstrap" };
-  } else if (agents === "missing") {
-    overall = "agents-missing";
-    next = { label: "Run `kaddo add agents` to install the Kaddo agent prompt packs.", command: "kaddo add agents" };
-  } else if (skills === "missing") {
-    overall = "skills-missing";
-    next = { label: "Run `kaddo add skills` to install reusable Kaddo skills.", command: "kaddo add skills" };
-  } else if (understand === "missing") {
-    overall = "scanned";
-    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]}).` };
-  } 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" };
-  } else if (roadmap !== "has-candidates") {
-    overall = "ready-for-roadmap";
-    next = { label: "Run `kaddo roadmap` to draft the roadmap from the current knowledge.", command: "kaddo roadmap" };
-  } else if (work_items === "none" || work_items === "none-ready") {
-    overall = "ready-for-work-item";
-    next = { label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap" };
-  } else {
-    overall = "ready-for-implementation";
-    next = adapters.length > 0 ? { label: "Implement the ready Work Item and run `kaddo guard`." } : { label: "Run `kaddo adapters list` and install the adapter for your preferred agent.", command: "kaddo adapters list" };
-  }
-  return { project_name: config.project.name, project_type: config.project.state, overall, signals, recommended_next_step: next };
+  if (scan2 === "missing") overall = "initialized";
+  else if (bootstrapBaseline === "incomplete") overall = "bootstrap-incomplete";
+  else if (agents === "missing") overall = "agents-missing";
+  else if (skills === "missing") overall = "skills-missing";
+  else if (understand === "missing") overall = "scanned";
+  else if (firstWeak) overall = "knowledge-incomplete";
+  else if (oq.summary.blocking_open > 0) overall = "needs-decisions";
+  else if (roadmap !== "has-candidates") overall = "ready-for-roadmap";
+  else if (work_items === "none" || work_items === "none-ready") overall = "ready-for-work-item";
+  else overall = "ready-for-implementation";
+  return {
+    project_name: config.project.name,
+    project_type: config.project.state,
+    overall,
+    signals,
+    recommended_next_step: { label: rec.label, ...rec.command ? { command: rec.command } : {} },
+    nextStepRecommendation: rec
+  };
 }
 
 // src/core/project-explain.ts
@@ -7965,6 +8131,7 @@ function buildProjectExplanation(dir) {
       "Run `kaddo owners suggest` for Work Items without code ownership."
     );
   }
+  const readiness = buildReadinessReport(dir);
   return {
     project,
     stack,
@@ -7985,7 +8152,8 @@ function buildProjectExplanation(dir) {
     mappedModules,
     missingKnowledge,
     suggestedNextSteps,
-    readiness: buildReadinessReport(dir)
+    readiness,
+    nextStepRecommendation: readiness.nextStepRecommendation
   };
 }
 function stateLabel(state) {
@@ -8166,7 +8334,7 @@ function renderExplanationHuman(exp) {
     lines.push("- Reason:");
     for (const r2 of assessment.reasons) lines.push(`  - ${r2}`);
   }
-  if (assessment.nextStep) lines.push(`- Next step: ${assessment.nextStep}`);
+  lines.push(`- Next step: ${exp.readiness.recommended_next_step.label}`);
   lines.push("");
   if (exp.suggestedNextSteps.length > 0) {
     lines.push("## Suggested Next Steps");
@@ -8183,9 +8351,11 @@ 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}`);
     lines.push(`- roadmap: ${s.roadmap}`);
     lines.push(`- work-items: ${s.work_items}`);
     lines.push(`- adapters: ${s.adapters.length > 0 ? s.adapters.join(", ") + " installed" : "none installed"}`);
@@ -8429,28 +8599,6 @@ function recommendedAgentsForState(state) {
       return ["capability-agent", "architecture-agent", "roadmap-agent"];
   }
 }
-function nextStepsForState2(state) {
-  switch (state) {
-    case "new":
-      return [
-        "Use roadmap-agent to shape an initial roadmap.",
-        "Use architecture-agent to outline the intended architecture."
-      ];
-    case "legacy":
-      return [
-        "Use legacy-agent to surface risks and unknowns before changing code.",
-        "Use architecture-agent to reconstruct the current architecture.",
-        "Use capability-agent to map existing capabilities."
-      ];
-    case "pre-ai":
-    default:
-      return [
-        "Use capability-agent to extract system capabilities.",
-        "Use architecture-agent to reconstruct the current architecture.",
-        "Use roadmap-agent to propose roadmap candidates."
-      ];
-  }
-}
 var LLM_INSTRUCTIONS = [
   "Use this context pack as the project baseline.",
   "Do not write code yet.",
@@ -8522,6 +8670,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({
@@ -8544,6 +8710,12 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
     }
   });
+  const nextStepRecommendation = resolveNextStep(dir, now);
+  const unifiedPhase = {
+    ...phase,
+    nextStep: nextStepRecommendation.label,
+    recommendedAgents: nextStepRecommendation.agent ? [nextStepRecommendation.agent] : phase.recommendedAgents
+  };
   return {
     version: CONTEXT_PACK_VERSION,
     generatedAt: now.toISOString(),
@@ -8572,8 +8744,10 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       artifacts: allArtifacts.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
     },
     layers,
+    knowledgeQuality,
     roadmap,
-    phase,
+    phase: unifiedPhase,
+    nextStepRecommendation,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -8581,12 +8755,12 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     skills: discoverInstalledSkills(dir).map((s) => s.id),
     mappedModules,
     missing,
-    // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
-    // contradicts the Current Phase block above it.
+    // VS-052/VS-073.2: the handoff is driven by the unified next step, so the pack never contradicts
+    // the Current Phase block above it.
     handoff: {
-      recommendedAgents: phase.recommendedAgents.length > 0 ? phase.recommendedAgents : recommendedAgentsForState(state),
-      nextSteps: phase.nextStep ? [phase.nextStep] : nextStepsForState2(state),
-      instructions: phase.llmInstructions.length > 0 ? phase.llmInstructions : LLM_INSTRUCTIONS,
+      recommendedAgents: unifiedPhase.recommendedAgents.length > 0 ? unifiedPhase.recommendedAgents : recommendedAgentsForState(state),
+      nextSteps: [nextStepRecommendation.label],
+      instructions: unifiedPhase.llmInstructions.length > 0 ? unifiedPhase.llmInstructions : LLM_INSTRUCTIONS,
       operatingRules: OPERATING_RULES
     }
   };
@@ -9090,24 +9264,16 @@ function runUnderstand() {
   console.log(`Project language: ${pack.project.language} (knowledge artifacts are written in this language)`);
   const exp = buildProjectExplanation(dir);
   const assessment = assessPhase(exp);
+  const rec = exp.nextStepRecommendation;
   console.log("");
   console.log(`Current phase: ${assessment.phase}`);
   if (assessment.reasons.length > 0) {
     console.log("Reason:");
     for (const r of assessment.reasons) console.log(`  - ${r}`);
   }
-  if (assessment.recommendedAgents.length > 0) {
-    console.log(`Recommended: ${assessment.recommendedAgents.join(", ")}`);
-  }
-  if (assessment.nextStep) {
-    console.log(`Next step: ${assessment.nextStep}`);
-  }
-  const readiness = exp.readiness;
-  if (readiness.overall === "initialized" || readiness.overall === "bootstrap-incomplete") {
-    console.log("");
-    console.log(`Project readiness: ${readiness.overall}.`);
-    console.log(`  \u2192 ${readiness.recommended_next_step.label}`);
-  }
+  if (rec.agent) console.log(`Recommended: ${rec.agent}`);
+  console.log(`Next step: ${rec.label}`);
+  if (rec.reason) console.log(`Why: ${rec.reason}`);
   const installedSkills = discoverInstalledSkills(dir);
   if (installedSkills.length > 0 && assessment.recommendedAgents.length > 0) {
     const recSkills = skillsForAgents(installedSkills, assessment.recommendedAgents);
@@ -11846,6 +12012,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.1",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {