@kaddo/cli 3.37.0 → 3.37.1

package/README.md

@@ -533,6 +533,7 @@ create --from roadmap → owners → guard → explain`.
 | 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

@@ -7745,14 +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", 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" }
-];
+// src/core/next-step.ts
 function roadmapSignal(dir) {
   const p2 = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p2)) return "missing";
@@ -7783,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",
@@ -7808,9 +7884,10 @@ 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";
@@ -7843,41 +7920,26 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
     resolved_questions: oq.summary.resolution.resolved,
     deferred_questions: oq.summary.resolution.deferred
   };
-  let overall;
-  let next;
   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" };
-  } 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: `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" };
-  } 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 };
+  let overall;
+  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
@@ -8069,6 +8131,7 @@ function buildProjectExplanation(dir) {
       "Run `kaddo owners suggest` for Work Items without code ownership."
     );
   }
+  const readiness = buildReadinessReport(dir);
   return {
     project,
     stack,
@@ -8089,7 +8152,8 @@ function buildProjectExplanation(dir) {
     mappedModules,
     missingKnowledge,
     suggestedNextSteps,
-    readiness: buildReadinessReport(dir)
+    readiness,
+    nextStepRecommendation: readiness.nextStepRecommendation
   };
 }
 function stateLabel(state) {
@@ -8270,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");
@@ -8292,7 +8356,6 @@ function renderExplanationHuman(exp) {
     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"}`);
@@ -8536,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.",
@@ -8669,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(),
@@ -8699,7 +8746,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     layers,
     knowledgeQuality,
     roadmap,
-    phase,
+    phase: unifiedPhase,
+    nextStepRecommendation,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -8707,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
     }
   };
@@ -9216,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);

package/package.json

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