@kaddo/cli 3.32.0 → 3.33.0

package/README.md

@@ -528,6 +528,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.30 | Antigravity adapter: `kaddo adapters install antigravity` (alias `kaddo export antigravity`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
 | v3.31 | Kiro adapter: `kaddo adapters install kiro` (alias `kaddo export kiro`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
 | v3.32 | Adapter discovery & status: `kaddo adapters list` (alias `ls`) and `kaddo adapters status` (alias `check`) — read-only catalog + per-adapter install state (missing/team-owned/injected/legacy-injected/full-generated/broken-markers), shared-`AGENTS.md` origin detection, `--json` |
+| v3.33 | Open questions resolution tracking: mark questions `[open]`/`[resolved]`/`[assumed]`/`[deferred]` (EN+ES); only `open` blocks readiness, so assumed/resolved/deferred decisions stop false blocks. `kaddo questions` shows status counts + `resolution_status` in JSON |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -2414,9 +2414,13 @@ open question):
 Before generating the roadmap, check **roadmap readiness** for open questions that affect scope,
 architecture or the MVP. Read \`kaddo://roadmap-readiness\` (MCP) or run \`kaddo questions\`.
 
-If readiness is \`needs_decisions\` (there are **blocking** open questions), do **not** generate the
-roadmap yet. Instead, list the blocking questions, propose reasonable assumptions for each, and ask
-the user to confirm, e.g.:
+Only questions with \`resolution_status = open\` block readiness. Questions marked \`[resolved]\`,
+\`[assumed]\` or \`[deferred]\` (EN) / \`[resuelta]\` \`[asumida]\` \`[diferida]\` (ES) do **not** block \u2014
+surface assumed ones as assumptions and deferred ones as out-of-scope, then continue.
+
+If readiness is \`needs_decisions\` (there are **blocking open** questions), do **not** generate the
+roadmap yet. Instead, list the blocking open questions, propose reasonable assumptions for each, and
+ask the user to confirm, e.g.:
 
 > Before generating the roadmap I found blocking open questions that affect the MVP scope.
 > I can proceed with these assumptions: \u2026 Confirm and continue?
@@ -2735,9 +2739,11 @@ Work Item actionable for a human.
 ## Readiness Gate (check first)
 
 For high-impact Work Items, check \`kaddo://roadmap-readiness\` (or \`kaddo questions\`) for
-**blocking** open questions related to this Work Item's scope. If any are unresolved, surface them
-and propose assumptions for the user to confirm before refining \u2014 don't bake in invisible
-assumptions.
+**blocking open** questions (\`resolution_status = open\`) related to this Work Item's scope. If any are
+open, surface them and propose assumptions for the user to confirm before refining \u2014 don't bake in
+invisible assumptions. Convert each open question into an explicit decision (\`[resolved]\`), an
+explicit assumption (\`[assumed]\`), or move it out of scope (\`[deferred]\`). Questions already marked
+resolved/assumed/deferred do not block.
 
 ## When to Use
 
@@ -3244,8 +3250,10 @@ new project. You propose; the human decides.
 
 Bootstrap surfaces \`## Open Questions\` in the knowledge files. Before moving to the roadmap,
 explicitly recommend reviewing them (\`kaddo questions\` / \`kaddo://roadmap-readiness\`) and turning
-**blocking** ones into resolved decisions or confirmed assumptions \u2014 so the roadmap isn't built on
-invisible assumptions.
+**blocking open** ones into resolved decisions or confirmed assumptions \u2014 so the roadmap isn't built
+on invisible assumptions. When you find unresolved questions, suggest marking each with a resolution
+token so Kaddo can track them: \`[open]\`, \`[resolved]\`, \`[assumed]\` or \`[deferred]\` (ES: \`[abierta]\`,
+\`[resuelta]\`, \`[asumida]\`, \`[diferida]\`). Only \`open\` questions block readiness.
 
 ## When to Use
 
@@ -3361,9 +3369,11 @@ human's, and commits/pushes/merges happen only with explicit human confirmation.
 ## Readiness Gate (check first)
 
 Before implementing a high-impact Work Item, check \`kaddo://roadmap-readiness\` (or
-\`kaddo questions\`) for **blocking** open questions about stack, architecture, persistence,
-authentication or the Work Item's scope. If any are unresolved, pause and ask the user to confirm
-assumptions or resolve them before writing code.
+\`kaddo questions\`) for **blocking open** questions (\`resolution_status = open\`) about stack,
+architecture, persistence, authentication or the Work Item's scope. Block only on questions still
+\`open\`; if a related question is already \`[assumed]\`, \`[resolved]\` or \`[deferred]\`, proceed and
+mention the relevant assumptions instead of pausing. If any blocking question is still open, pause and
+ask the user to confirm assumptions or resolve them before writing code.
 
 ## When to Use
 
@@ -8207,6 +8217,24 @@ function renderDeliveryLifecycle(wi) {
 }
 
 // src/core/open-questions.ts
+var RESOLUTION_TOKENS = {
+  open: "open",
+  resolved: "resolved",
+  assumed: "assumed",
+  deferred: "deferred",
+  abierta: "open",
+  resuelta: "resolved",
+  asumida: "assumed",
+  diferida: "deferred"
+};
+function parseResolution(line) {
+  const m = line.match(/^\[([a-zA-Záéí]+)\]\s*(.*)$/);
+  if (m) {
+    const status = RESOLUTION_TOKENS[m[1].toLowerCase()];
+    if (status) return { text: m[2].trim(), resolution_status: status };
+  }
+  return { text: line.trim(), resolution_status: "open" };
+}
 var SOURCES = [
   "knowledge/business/business.md",
   "knowledge/product/product.md",
@@ -8298,10 +8326,17 @@ function extractFromMarkdown(md) {
   for (let i = start + 1; i < lines.length; i++) {
     const line = lines[i];
     if (/^#{1,6}\s+/.test(line)) break;
+    const meta = line.match(/^\s+(?:[-*])\s+(\w+)\s*:\s*(.+?)\s*$/);
+    if (meta && out.length > 0) {
+      if (meta[1].toLowerCase() === "note") out[out.length - 1].resolution_note = meta[2].trim();
+      continue;
+    }
     const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/);
     if (m) {
-      const q = m[1].trim();
-      if (q && !/^_.*_$/.test(q)) out.push(q);
+      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 });
     }
   }
   return out;
@@ -8335,29 +8370,37 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
     } catch {
       continue;
     }
-    for (const q of extractFromMarkdown(md)) {
+    for (const eq of extractFromMarkdown(md)) {
       seq += 1;
-      const { classification, reason } = classifyQuestion(q);
+      const { classification, reason } = classifyQuestion(eq.text);
       questions.push({
         id: `OQ-${String(seq).padStart(3, "0")}`,
         source,
         section: "Open Questions",
-        question: q,
+        question: eq.text,
         classification,
+        resolution_status: eq.resolution_status,
         reason,
-        ...classification === "blocking" ? { suggested_assumption: suggestedAssumption(q) } : {}
+        ...eq.resolution_note ? { resolution_note: eq.resolution_note } : {},
+        ...classification === "blocking" && eq.resolution_status === "open" ? { suggested_assumption: suggestedAssumption(eq.text) } : {}
       });
     }
   }
   const blocking = questions.filter((q) => q.classification === "blocking");
   const important = questions.filter((q) => q.classification === "important");
   const deferred = questions.filter((q) => q.classification === "deferred");
+  const blockingOpen = blocking.filter((q) => q.resolution_status === "open");
+  const importantOpen = important.filter((q) => q.resolution_status === "open");
+  const byStatus = (s) => questions.filter((q) => q.resolution_status === s);
+  const resolved = byStatus("resolved");
+  const assumed = byStatus("assumed");
+  const deferredStatus = byStatus("deferred");
   let readiness;
   if (questions.length === 0) readiness = "unknown";
-  else if (blocking.length > 0) readiness = "needs_decisions";
+  else if (blockingOpen.length > 0) readiness = "needs_decisions";
   else readiness = "ready";
-  const suggested_assumptions = blocking.map((q) => q.suggested_assumption).filter(Boolean);
-  const recommended_next_step = readiness === "needs_decisions" ? "Confirm suggested assumptions with the user (resolve, assume or defer blocking questions) before generating the roadmap." : readiness === "ready" ? "No blocking questions \u2014 you can proceed to the roadmap (review important questions when convenient)." : "No open questions found. Run `kaddo bootstrap` to capture early questions, or proceed.";
+  const suggested_assumptions = blockingOpen.map((q) => q.suggested_assumption).filter(Boolean);
+  const recommended_next_step = readiness === "needs_decisions" ? "Confirm suggested assumptions with the user (resolve, assume or defer blocking open questions) before generating the roadmap." : readiness === "ready" ? "No blocking open questions \u2014 you can proceed to the roadmap. Surfaced assumptions/deferred items are informational." : "No open questions found. Run `kaddo bootstrap` to capture early questions, or proceed.";
   return {
     generated_at: now.toISOString(),
     project,
@@ -8366,12 +8409,23 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
       roadmap_readiness: readiness,
       blocking: blocking.length,
       important: important.length,
-      deferred: deferred.length
+      deferred: deferred.length,
+      blocking_open: blockingOpen.length,
+      important_open: importantOpen.length,
+      resolution: {
+        open: byStatus("open").length,
+        resolved: resolved.length,
+        assumed: assumed.length,
+        deferred: deferredStatus.length
+      }
     },
     questions,
     blocking_questions: blocking,
     important_questions: important,
     deferred_questions: deferred,
+    resolved_questions: resolved,
+    assumed_questions: assumed,
+    deferred_status_questions: deferredStatus,
     suggested_assumptions,
     recommended_next_step
   };
@@ -8385,18 +8439,18 @@ function renderOpenQuestionsMarkdown(r) {
   L.push("## Summary", "");
   L.push(`- Open questions found: ${r.summary.open_questions}`);
   L.push(`- Roadmap readiness: ${r.summary.roadmap_readiness}`);
-  L.push(`- Blocking: ${r.summary.blocking}`);
-  L.push(`- Important: ${r.summary.important}`);
-  L.push(`- Deferred: ${r.summary.deferred}`);
+  L.push(`- By resolution \u2014 open: ${r.summary.resolution.open}, resolved: ${r.summary.resolution.resolved}, assumed: ${r.summary.resolution.assumed}, deferred: ${r.summary.resolution.deferred}`);
+  L.push(`- Blocking open: ${r.summary.blocking_open}, important open: ${r.summary.important_open}`);
   L.push("");
   if (r.summary.open_questions === 0) {
     L.push("No `## Open Questions` sections found in business / product / codebase / roadmap.", "");
     L.push("## Recommended Next Step", "", r.recommended_next_step, "");
     return L.join("\n");
   }
-  L.push("## Blocking Questions", "");
-  if (r.blocking_questions.length === 0) L.push("_None._", "");
-  for (const q of r.blocking_questions) {
+  const blockingOpen = r.blocking_questions.filter((q) => q.resolution_status === "open");
+  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}`);
@@ -8404,13 +8458,18 @@ function renderOpenQuestionsMarkdown(r) {
     if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
     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}_` : ""}`);
+    L.push("");
+  };
+  renderStatusList("Resolved", r.resolved_questions);
+  renderStatusList("Assumed (decisions to revisit)", r.assumed_questions);
+  renderStatusList("Deferred (out of current scope)", r.deferred_status_questions);
   L.push("## Important Questions", "");
   if (r.important_questions.length === 0) L.push("_None._");
-  for (const q of r.important_questions) L.push(`- ${q.question}`);
-  L.push("");
-  L.push("## Deferred Questions", "");
-  if (r.deferred_questions.length === 0) L.push("_None._");
-  for (const q of r.deferred_questions) L.push(`- ${q.question}`);
+  for (const q of r.important_questions) L.push(`- [${q.resolution_status}] ${q.question}`);
   L.push("");
   if (r.suggested_assumptions.length > 0) {
     L.push("## Suggested Assumptions", "");
@@ -8497,9 +8556,9 @@ function runUnderstand() {
     console.log("  Suggested agent: graph-agent (see .kaddo/graph-hints.md)");
   }
   const oq = buildOpenQuestionsReport(dir);
-  if (oq.summary.blocking > 0) {
+  if (oq.summary.blocking_open > 0) {
     console.log("");
-    console.log(`Open questions: ${oq.summary.blocking} blocking decision(s) before the roadmap (roadmap readiness: ${oq.summary.roadmap_readiness}).`);
+    console.log(`Open questions: ${oq.summary.blocking_open} blocking open decision(s) before the roadmap (roadmap readiness: ${oq.summary.roadmap_readiness}).`);
     console.log("  \u2192 Run `kaddo questions` to review them, then resolve, assume or defer before `kaddo create --from roadmap`.");
   }
   const active = activeWorkItems(dir);
@@ -12280,19 +12339,22 @@ function runQuestions(opts = {}) {
     console.log(serializeOpenQuestionsJson(report));
     return;
   }
+  const s = report.summary;
   console.log("");
-  console.log(`Open questions detected: ${report.summary.open_questions}`);
-  console.log(`Roadmap readiness: ${report.summary.roadmap_readiness === "needs_decisions" ? "needs decisions" : report.summary.roadmap_readiness}`);
+  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) => {
     if (qs.length === 0) return;
     console.log("");
     console.log(`${title}:`);
-    for (const q of qs.slice(0, 8)) console.log(`- ${q.question}`);
+    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`);
   };
-  list2("Blocking", report.blocking_questions);
-  list2("Important", report.important_questions);
-  list2("Deferred", report.deferred_questions);
+  list2("Blocking (open)", report.blocking_questions.filter((q) => q.resolution_status === "open"));
+  list2("Resolved", report.resolved_questions);
+  list2("Assumed", report.assumed_questions);
+  list2("Deferred", report.deferred_status_questions);
   console.log("");
   console.log("Suggested next:");
   console.log(report.recommended_next_step);
@@ -12444,9 +12506,9 @@ function renderAdapterMarkdown(ctx, target) {
   L.push("Read `knowledge/business/business.md`, `knowledge/product/product.md`,");
   L.push("`knowledge/tech/codebase.md`, and `.kaddo/reports/questions-report.md` if available.");
   L.push("");
-  L.push("Check open-questions readiness first. **If blocking open questions exist, ask the user to");
-  L.push("resolve, assume or defer them before generating the roadmap** \u2014 never build the roadmap on");
-  L.push("invisible assumptions.");
+  L.push("Check open-questions readiness first. **If blocking questions with resolution_status = open");
+  L.push("exist, ask the user to resolve, assume or defer them before generating the roadmap.** Assumed,");
+  L.push("resolved or deferred questions should be surfaced for context, but should not block execution.");
   L.push("");
   L.push("## Before implementation", "");
   L.push("Read the target Work Item in `knowledge/delivery/work-items/`, `.kaddo/context-pack.md`,");
@@ -12568,8 +12630,9 @@ function renderKaddoBlock(ctx) {
   L.push("");
   for (const line of commandFallbackSection(ctx.packageManager, "### ")) L.push(line);
   L.push("### Before roadmap work", "");
-  L.push("Check open-questions readiness first. If blocking open questions exist, ask the user to");
-  L.push("resolve, assume or defer them before generating the roadmap.");
+  L.push("Check open-questions readiness first. If blocking questions with resolution_status = open");
+  L.push("exist, ask the user to resolve, assume or defer them. Assumed/resolved/deferred questions");
+  L.push("should be surfaced, but should not block execution.");
   L.push("");
   L.push("### Before implementation", "");
   L.push("Read the target Work Item in `knowledge/delivery/work-items/`, `.kaddo/context-pack.md`,");

package/package.json

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