@kaddo/cli 3.37.0 → 3.38.0

package/README.md

@@ -533,6 +533,8 @@ 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 |
+| v3.38 | Open-question source locations: `kaddo questions` shows each question's `Source` (path:line), `Status`, `Severity`, `Note` + a copy/paste resolution example and localized how-to-resolve guide; JSON/report/MCP carry `sourcePath`, `line`, `raw`, `note` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -7205,10 +7205,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: text3, resolution_status } = parseResolution(raw);
-      if (text3) out.push({ text: text3, resolution_status });
+      const bullet = m[1].trim();
+      if (!bullet || /^_.*_$/.test(bullet)) continue;
+      const { text: text3, resolution_status } = parseResolution(bullet);
+      if (text3) out.push({ text: text3, resolution_status, line: i + 1, raw: line.trim() });
     }
   }
   return out;
@@ -7248,12 +7248,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) } : {}
       });
     }
@@ -7323,17 +7326,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);
@@ -7745,14 +7754,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 +7785,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." };
+}
+
+// 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 +7893,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 +7929,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 +8140,7 @@ function buildProjectExplanation(dir) {
       "Run `kaddo owners suggest` for Work Items without code ownership."
     );
   }
+  const readiness = buildReadinessReport(dir);
   return {
     project,
     stack,
@@ -8089,7 +8161,8 @@ function buildProjectExplanation(dir) {
     mappedModules,
     missingKnowledge,
     suggestedNextSteps,
-    readiness: buildReadinessReport(dir)
+    readiness,
+    nextStepRecommendation: readiness.nextStepRecommendation
   };
 }
 function stateLabel(state) {
@@ -8270,7 +8343,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 +8365,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 +8608,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 +8719,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 +8755,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 +8764,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 +9273,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);
@@ -13403,7 +13452,8 @@ function runDrift(opts = {}) {
 // src/commands/questions.ts
 function runQuestions(opts = {}) {
   const dir = cwd();
-  requireConfig(dir);
+  const config = requireConfig(dir);
+  const es = projectLanguage(config) === "es";
   const report = buildOpenQuestionsReport(dir);
   if (opts.output) {
     intro2("kaddo questions");
@@ -13422,22 +13472,67 @@ function runQuestions(opts = {}) {
   console.log(`Open questions detected: ${s.open_questions}`);
   console.log(`By resolution \u2014 open: ${s.resolution.open}, resolved: ${s.resolution.resolved}, assumed: ${s.resolution.assumed}, deferred: ${s.resolution.deferred}`);
   console.log(`Roadmap readiness: ${s.roadmap_readiness === "needs_decisions" ? "needs decisions" : s.roadmap_readiness} (blocking open: ${s.blocking_open}, important open: ${s.important_open})`);
-  const list2 = (title, qs) => {
+  const list2 = (title, qs, opts2 = {}) => {
     if (qs.length === 0) return;
     console.log("");
     console.log(`${title}:`);
-    for (const q of qs.slice(0, 8)) console.log(`- ${q.question}${q.resolution_note ? ` \u2014 ${q.resolution_note}` : ""}`);
-    if (qs.length > 8) console.log(`  \u2026and ${qs.length - 8} more`);
+    console.log("");
+    qs.slice(0, 12).forEach((q, i) => {
+      console.log(`${i + 1}. ${q.question}`);
+      console.log(`   Source: ${q.sourcePath}:${q.line}`);
+      console.log(`   Status: ${q.resolution_status}`);
+      console.log(`   Severity: ${q.classification}`);
+      if (q.note) console.log(`   Note: ${q.note}`);
+      if (opts2.example && q.resolution_status === "open") {
+        console.log("   Suggested action:");
+        console.log(`     ${es ? "Cambia [open] por [resolved], [assumed] o [deferred]." : "Change [open] to [resolved], [assumed] or [deferred]."}`);
+        console.log("   Example:");
+        console.log(`     - [assumed] ${q.question}`);
+        console.log(`       - note: ${es ? "<supuesto editable para el MVP>" : "<editable assumption for the MVP>"}`);
+      }
+      console.log("");
+    });
+    if (qs.length > 12) console.log(`  \u2026and ${qs.length - 12} more`);
   };
-  list2("Blocking (open)", report.blocking_questions.filter((q) => q.resolution_status === "open"));
+  list2("Blocking (open)", report.blocking_questions.filter((q) => q.resolution_status === "open"), { example: true });
+  list2("Important (open)", report.important_questions.filter((q) => q.resolution_status === "open"));
   list2("Resolved", report.resolved_questions);
   list2("Assumed", report.assumed_questions);
   list2("Deferred", report.deferred_status_questions);
+  printResolutionGuide(es);
   console.log("");
   console.log("Suggested next:");
   console.log(report.recommended_next_step);
   printCommandFooter("questions");
 }
+function printResolutionGuide(es) {
+  console.log("");
+  if (es) {
+    console.log("C\xF3mo resolver");
+    console.log("");
+    console.log("Edita el archivo indicado en Source y cambia el marcador:");
+    console.log("  [open]     \u2192 sigue abierta");
+    console.log("  [resolved] \u2192 respuesta confirmada");
+    console.log("  [assumed]  \u2192 supuesto seguro por ahora");
+    console.log("  [deferred] \u2192 decisi\xF3n aplazada");
+    console.log("");
+    console.log("Agrega una nota debajo de la pregunta cuando sea posible:");
+    console.log("  - [assumed] \xBFPregunta?");
+    console.log("    - note: Se asume X para el MVP porque Y.");
+  } else {
+    console.log("How to resolve");
+    console.log("");
+    console.log("Edit the file shown in Source and change the marker:");
+    console.log("  [open]     \u2192 still unresolved");
+    console.log("  [resolved] \u2192 confirmed answer");
+    console.log("  [assumed]  \u2192 safe assumption for now");
+    console.log("  [deferred] \u2192 intentionally postponed");
+    console.log("");
+    console.log("Add a note below the question when possible:");
+    console.log("  - [assumed] Question?");
+    console.log("    - note: Assume X for the MVP because Y.");
+  }
+}
 
 // src/commands/adapters.ts
 var ADAPTER_LIST = ADAPTERS.map((a) => a.id).join(", ");

package/package.json

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