@kaddo/mcp 3.37.0 → 3.38.0

package/dist/index.js

@@ -1916,10 +1916,10 @@ function extractFromMarkdown(md) {
     }
     const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/);
     if (m) {
-      const raw = m[1].trim();
-      if (!raw || /^_.*_$/.test(raw)) continue;
-      const { text: text2, resolution_status } = parseResolution(raw);
-      if (text2) out.push({ text: text2, resolution_status });
+      const bullet = m[1].trim();
+      if (!bullet || /^_.*_$/.test(bullet)) continue;
+      const { text: text2, resolution_status } = parseResolution(bullet);
+      if (text2) out.push({ text: text2, resolution_status, line: i + 1, raw: line.trim() });
     }
   }
   return out;
@@ -1959,12 +1959,15 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
       questions.push({
         id: `OQ-${String(seq).padStart(3, "0")}`,
         source,
+        sourcePath: source,
+        line: eq.line,
+        raw: eq.raw,
         section: "Open Questions",
         question: eq.text,
         classification,
         resolution_status: eq.resolution_status,
         reason,
-        ...eq.resolution_note ? { resolution_note: eq.resolution_note } : {},
+        ...eq.resolution_note ? { resolution_note: eq.resolution_note, note: eq.resolution_note } : {},
         ...classification === "blocking" && eq.resolution_status === "open" ? { suggested_assumption: suggestedAssumption(eq.text) } : {}
       });
     }
@@ -2034,17 +2037,23 @@ function renderOpenQuestionsMarkdown(r) {
   L.push("## Blocking Open Questions", "");
   if (blockingOpen.length === 0) L.push("_None \u2014 nothing blocks readiness._", "");
   for (const q of blockingOpen) {
-    L.push(`### ${q.id}`, "");
-    L.push(`- Source: \`${q.source}\``);
-    L.push(`- Question: ${q.question}`);
+    L.push(`### ${q.question}`, "");
+    L.push(`- Status: ${q.resolution_status}`);
+    L.push(`- Severity: ${q.classification}`);
+    L.push(`- Source: \`${q.sourcePath}:${q.line}\``);
     L.push(`- Reason: ${q.reason}`);
-    if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
+    L.push("");
+    L.push("Suggested action:", "");
+    L.push("```md");
+    L.push(`- [assumed] ${q.question}`);
+    L.push(`  - note: ${q.suggested_assumption ?? "<editable assumption for the MVP>"}`);
+    L.push("```");
     L.push("");
   }
   const renderStatusList = (title, items) => {
     L.push(`## ${title}`, "");
     if (items.length === 0) L.push("_None._");
-    for (const q of items) L.push(`- ${q.question}${q.resolution_note ? ` \u2014 _${q.resolution_note}_` : ""}`);
+    for (const q of items) L.push(`- ${q.question} \u2014 \`${q.sourcePath}:${q.line}\`${q.note ? ` \u2014 _${q.note}_` : ""}`);
     L.push("");
   };
   renderStatusList("Resolved", r.resolved_questions);
@@ -2218,14 +2227,7 @@ function buildAdapterStatuses(dir) {
   });
 }
 
-// ../cli/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" }
-];
+// ../cli/src/core/next-step.ts
 function roadmapSignal(dir) {
   const p = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p)) return "missing";
@@ -2256,8 +2258,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: "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.` };
+  }
+  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." };
+}
+
+// ../cli/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",
@@ -2281,9 +2366,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 scan = exists(join(dir, ".kaddo", "scan.json")) ? "available" : "missing";
@@ -2316,41 +2402,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 (scan === "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 (scan === "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
+  };
 }
 
 // ../cli/src/core/project-explain.ts
@@ -2542,6 +2613,7 @@ function buildProjectExplanation(dir) {
       "Run `kaddo owners suggest` for Work Items without code ownership."
     );
   }
+  const readiness = buildReadinessReport(dir);
   return {
     project,
     stack,
@@ -2562,7 +2634,8 @@ function buildProjectExplanation(dir) {
     mappedModules,
     missingKnowledge,
     suggestedNextSteps,
-    readiness: buildReadinessReport(dir)
+    readiness,
+    nextStepRecommendation: readiness.nextStepRecommendation
   };
 }
 function stateLabel(state) {
@@ -2743,7 +2816,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");
@@ -2765,7 +2838,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"}`);
@@ -4120,28 +4192,6 @@ function recommendedAgentsForState(state) {
       return ["capability-agent", "architecture-agent", "roadmap-agent"];
   }
 }
-function nextStepsForState(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.",
@@ -4253,6 +4303,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(),
@@ -4283,7 +4339,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     layers,
     knowledgeQuality,
     roadmap,
-    phase,
+    phase: unifiedPhase,
+    nextStepRecommendation,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -4291,12 +4348,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] : nextStepsForState(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
     }
   };

package/package.json

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