@kaddo/cli 3.37.1 → 3.38.0

package/README.md

@@ -534,6 +534,7 @@ create --from roadmap → owners → guard → explain`.
 | 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);
@@ -7833,7 +7842,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   }
   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.` };
+    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") {
@@ -13443,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");
@@ -13462,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.1",
+  "version": "3.38.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {