@kaddo/mcp 3.25.0 → 3.26.0

package/dist/index.js

@@ -2702,11 +2702,23 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
   const graphMult = GRAPH_MULT[graphQuality] ?? 0;
   const archH = round2(a.architecture_discovery_hours_saved_when_graph_good * graphMult);
   const guard = buildGuardHistory(dir);
-  const driftSavings = guard.available && guard.resolved > 0 ? {
-    available: true,
-    hours: round2(guard.resolved * a.rework_hours_avoided_per_resolved_drift),
-    formula: `${guard.resolved} resolved drift warnings \xD7 ${a.rework_hours_avoided_per_resolved_drift} h`
-  } : { available: false, hours: 0, reason: "Guard history is not persisted yet." };
+  let driftSavings;
+  if (!guard.available) {
+    driftSavings = { available: false, hours: 0, reason: "Guard history is not persisted yet." };
+  } else if (guard.resolved > 0) {
+    driftSavings = {
+      available: true,
+      hours: round2(guard.resolved * a.rework_hours_avoided_per_resolved_drift),
+      formula: `${guard.resolved} resolved drift warnings \xD7 ${a.rework_hours_avoided_per_resolved_drift} h`
+    };
+  } else {
+    driftSavings = {
+      available: true,
+      hours: 0,
+      formula: `0 resolved drift warnings \xD7 ${a.rework_hours_avoided_per_resolved_drift} h`,
+      reason: "Guard history exists, but no resolved drift warnings have been recorded yet."
+    };
+  }
   const totalHours = round2(ctxPrepH + reviewH + clarH + onboardH + archH + driftSavings.hours);
   const totalValue = Math.round(totalHours * a.hourly_cost);
   const reasons = [];
@@ -2721,15 +2733,27 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
     level = "Medium";
     reasons.push("Strong knowledge and graph evidence.");
   }
-  if (!guard.available) reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
-  else reasons.push(`Guard history available (${guard.resolved} resolved drift warning(s)).`);
+  if (!guard.available) {
+    reasons.push("Guard history is not persisted yet \u2014 avoided rework is not estimated.");
+  } else if (guard.resolved > 0) {
+    reasons.push(`Guard history available (${guard.resolved} resolved drift warning(s)).`);
+  } else {
+    reasons.push("Guard history available, but no resolved drift warnings have been recorded yet.");
+  }
   reasons.push(source === "file" ? "Assumptions come from `.kaddo/savings.yml`." : "Savings assumptions are defaults and should be calibrated.");
   const actions = [];
   if (source === "default") actions.push("Run `kaddo savings init` to customize assumptions.");
   actions.push("Calibrate hourly cost and team assumptions with real team data.");
   actions.push("Run `kaddo impact` to verify the underlying evidence quality.");
   actions.push("Use this report as directional evidence, not accounting data.");
-  actions.push("Future: persist Guard history to estimate avoided rework.");
+  if (!guard.available) {
+    actions.push("Future: persist Guard history to estimate avoided rework.");
+  } else if (guard.resolved === 0) {
+    actions.push("Continue running `kaddo guard --record` before important commits to capture resolved drift warnings.");
+    if (guard.open > 0) actions.push("Review open drift warnings with `kaddo drift`.");
+  } else {
+    actions.push("Use drift history to calibrate `rework_hours_avoided_per_resolved_drift`.");
+  }
   return {
     generated_at: now.toISOString(),
     project: impact.project,
@@ -2755,7 +2779,9 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       graph_nodes: impact.graph_quality.available ? impact.graph_quality.nodes : null,
       graph_edges: impact.graph_quality.available ? impact.graph_quality.edges : null,
       context_readiness: readiness,
-      guard_history_available: guard.available
+      guard_history_available: guard.available,
+      guard_runs_recorded: guard.total_runs,
+      resolved_drift_warnings: guard.resolved
     },
     estimated_savings: {
       context_preparation: { hours: ctxPrepH, formula: `${completed} Work Items \xD7 ${a.context_preparation_minutes_saved_per_work_item} min` },
@@ -2805,7 +2831,13 @@ function renderSavingsMarkdown(r) {
   if (e.graph_nodes !== null) L.push(`- Graph nodes: ${e.graph_nodes}`);
   if (e.graph_edges !== null) L.push(`- Graph edges: ${e.graph_edges}`);
   L.push(`- Context readiness: ${e.context_readiness}`);
-  L.push("- Guard history: not available");
+  if (e.guard_history_available) {
+    L.push("- Guard history: available");
+    L.push(`- Guard runs recorded: ${e.guard_runs_recorded}`);
+    L.push(`- Resolved drift warnings: ${e.resolved_drift_warnings}`);
+  } else {
+    L.push("- Guard history: not available");
+  }
   L.push("");
   L.push("## Estimated Savings", "");
   const s = r.estimated_savings;
@@ -2822,7 +2854,9 @@ function renderSavingsMarkdown(r) {
   L.push("### Drift Prevention", "");
   if (s.drift_prevention.available) {
     L.push(`- Formula: ${s.drift_prevention.formula}`);
-    L.push(`- Estimated: ${s.drift_prevention.hours} h`, "");
+    L.push(`- Estimated: ${s.drift_prevention.hours} h`);
+    if (s.drift_prevention.reason) L.push(`- Reason: ${s.drift_prevention.reason}`);
+    L.push("");
   } else {
     L.push("- Not available yet.");
     L.push(`- Reason: ${s.drift_prevention.reason}`, "");
@@ -2956,6 +2990,235 @@ function serializeDriftJson(r) {
   return JSON.stringify(out, null, 2) + "\n";
 }
 
+// ../cli/src/core/open-questions.ts
+var SOURCES = [
+  "knowledge/business/business.md",
+  "knowledge/product/product.md",
+  "knowledge/tech/codebase.md",
+  "knowledge/delivery/roadmap.md"
+];
+var BLOCKING = [
+  "mvp",
+  "stack",
+  "arquitect",
+  "architecture",
+  "api",
+  "web app",
+  "webapp",
+  "cli",
+  "backend",
+  "auth",
+  "autenticaci",
+  "persist",
+  "base de datos",
+  "database",
+  "roadmap",
+  "alcance",
+  "scope",
+  "primera versi\xF3n",
+  "primera version",
+  "first version",
+  "fastify",
+  "nestjs",
+  "framework"
+];
+var DEFERRED = [
+  "integraci",
+  "integration",
+  "analytics",
+  "notificaci",
+  "notification",
+  "google calendar",
+  "eventbrite",
+  "meetup",
+  "dashboard",
+  "multi-tenant",
+  "multitenant",
+  "mobile",
+  "m\xF3vil",
+  "pago",
+  "payment",
+  "ticketing",
+  "multiple tracks",
+  "m\xFAltiples tracks",
+  "webhook"
+];
+var IMPORTANT = [
+  "validaci",
+  "validation",
+  "paginaci",
+  "pagination",
+  "soft delete",
+  "sponsor",
+  "agenda",
+  "ubicaci",
+  "location",
+  "rol",
+  "role",
+  "permis",
+  "permission"
+];
+function matchesAny(text2, keywords) {
+  return keywords.some((k) => text2.includes(k));
+}
+function classifyQuestion(question) {
+  const t = question.toLowerCase();
+  if (matchesAny(t, BLOCKING)) {
+    return { classification: "blocking", reason: "Affects scope, architecture or the first Work Items." };
+  }
+  if (matchesAny(t, DEFERRED) && !matchesAny(t, IMPORTANT)) {
+    return { classification: "deferred", reason: "Can be moved to a later phase." };
+  }
+  if (matchesAny(t, IMPORTANT)) {
+    return { classification: "important", reason: "Relevant, but a temporary assumption can unblock progress." };
+  }
+  return { classification: "important", reason: "Relevant, but a temporary assumption can unblock progress." };
+}
+function extractFromMarkdown(md) {
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^#{1,6}\s+open questions\s*$/i.test(l.trim()) || /^#{1,6}\s+preguntas abiertas\s*$/i.test(l.trim()));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{1,6}\s+/.test(line)) break;
+    const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/);
+    if (m) {
+      const q = m[1].trim();
+      if (q && !/^_.*_$/.test(q)) out.push(q);
+    }
+  }
+  return out;
+}
+function suggestedAssumption(question) {
+  const t = question.toLowerCase();
+  if (matchesAny(t, ["api", "web app", "webapp", "cli", "backend"])) {
+    return "Start as a backend API to keep the initial scope small.";
+  }
+  if (matchesAny(t, ["auth", "autenticaci"])) {
+    return "No authentication in the MVP.";
+  }
+  if (matchesAny(t, ["fastify", "nestjs", "framework", "stack"])) {
+    return "Choose the lighter stack option to minimize MVP scope.";
+  }
+  if (matchesAny(t, ["persist", "base de datos", "database"])) {
+    return "Use a simple local datastore (e.g. SQLite) for the MVP.";
+  }
+  return "Proceed with the smallest reasonable MVP interpretation and revisit later.";
+}
+function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
+  const project = loadConfig(dir)?.project.name ?? "unknown";
+  const questions = [];
+  let seq = 0;
+  for (const source of SOURCES) {
+    const p = join(dir, source);
+    if (!exists(p)) continue;
+    let md;
+    try {
+      md = readFile(p);
+    } catch {
+      continue;
+    }
+    for (const q of extractFromMarkdown(md)) {
+      seq += 1;
+      const { classification, reason } = classifyQuestion(q);
+      questions.push({
+        id: `OQ-${String(seq).padStart(3, "0")}`,
+        source,
+        section: "Open Questions",
+        question: q,
+        classification,
+        reason,
+        ...classification === "blocking" ? { suggested_assumption: suggestedAssumption(q) } : {}
+      });
+    }
+  }
+  const blocking = questions.filter((q) => q.classification === "blocking");
+  const important = questions.filter((q) => q.classification === "important");
+  const deferred = questions.filter((q) => q.classification === "deferred");
+  let readiness;
+  if (questions.length === 0) readiness = "unknown";
+  else if (blocking.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.";
+  return {
+    generated_at: now.toISOString(),
+    project,
+    summary: {
+      open_questions: questions.length,
+      roadmap_readiness: readiness,
+      blocking: blocking.length,
+      important: important.length,
+      deferred: deferred.length
+    },
+    questions,
+    blocking_questions: blocking,
+    important_questions: important,
+    deferred_questions: deferred,
+    suggested_assumptions,
+    recommended_next_step
+  };
+}
+function renderOpenQuestionsMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Open Questions Readiness Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push("");
+  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("");
+  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) {
+    L.push(`### ${q.id}`, "");
+    L.push(`- Source: \`${q.source}\``);
+    L.push(`- Question: ${q.question}`);
+    L.push(`- Reason: ${q.reason}`);
+    if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
+    L.push("");
+  }
+  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}`);
+  L.push("");
+  if (r.suggested_assumptions.length > 0) {
+    L.push("## Suggested Assumptions", "");
+    for (const a of r.suggested_assumptions) L.push(`- ${a}`);
+    L.push("");
+  }
+  L.push("## Recommended Next Step", "", r.recommended_next_step, "");
+  return L.join("\n");
+}
+function serializeOpenQuestionsJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+function roadmapReadinessSummary(dir) {
+  const r = buildOpenQuestionsReport(dir);
+  return {
+    roadmap_readiness: r.summary.roadmap_readiness,
+    blocking_questions: r.summary.blocking,
+    important_questions: r.summary.important,
+    deferred_questions: r.summary.deferred,
+    suggested_assumptions: r.suggested_assumptions,
+    recommended_next_step: r.summary.roadmap_readiness === "needs_decisions" ? "Resolve, assume, or defer blocking questions before generating roadmap." : r.recommended_next_step
+  };
+}
+
 // src/workitems.ts
 import matter7 from "gray-matter";
 var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
@@ -3206,6 +3469,31 @@ var RESOURCES = [
       }
       return [{ uri: "kaddo://guard-history", text: runs, mimeType: "application/jsonl" }];
     }
+  },
+  {
+    uri: "kaddo://open-questions",
+    name: "Kaddo open questions",
+    description: "Open questions from business/product/codebase/roadmap, classified for the readiness gate.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://open-questions", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      const r = buildOpenQuestionsReport(root);
+      return [{ uri: "kaddo://open-questions", text: JSON.stringify({ questions: r.questions }, null, 2), mimeType: "application/json" }];
+    }
+  },
+  {
+    uri: "kaddo://roadmap-readiness",
+    name: "Kaddo roadmap readiness",
+    description: "Decision-oriented roadmap readiness summary (blocking/important/deferred + suggested assumptions).",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://roadmap-readiness", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [{ uri: "kaddo://roadmap-readiness", text: JSON.stringify(roadmapReadinessSummary(root), null, 2), mimeType: "application/json" }];
+    }
   }
 ];
 
@@ -4015,6 +4303,21 @@ function generateDriftReport(root, opts = {}) {
     next_suggested_resources: ["kaddo://drift-report"]
   };
 }
+function generateQuestionsReport(root, opts = {}) {
+  requireConfig(root);
+  const format = opts.format ?? "markdown";
+  const report = buildOpenQuestionsReport(root);
+  const content = format === "json" ? serializeOpenQuestionsJson(report) : renderOpenQuestionsMarkdown(report);
+  const out = opts.output ?? `.kaddo/reports/questions-report.${format === "json" ? "json" : "md"}`;
+  writeDerived(root, out, content);
+  return {
+    status: "ok",
+    files_written: [out.replace(/\\/g, "/")],
+    summary: `Open questions report generated (readiness: ${report.summary.roadmap_readiness}, ${report.summary.blocking} blocking).`,
+    warnings: report.summary.blocking > 0 ? [`${report.summary.blocking} blocking question(s) before the roadmap.`] : [],
+    next_suggested_resources: ["kaddo://open-questions", "kaddo://roadmap-readiness"]
+  };
+}
 function generateCapsuleDraft(root) {
   const config = requireConfig(root);
   requireKnowledge(root);
@@ -4248,6 +4551,22 @@ function createServer(root) {
       () => generateDriftReport(root, { format: args.format, output: args.output })
     )
   );
+  server.registerTool(
+    "kaddo_generate_questions_report",
+    {
+      title: "Generate open-questions report",
+      description: `Write the Open Questions readiness report under .kaddo/reports/ (classifies blocking/important/deferred). Does NOT resolve questions. ${DERIVED_NOTE}`,
+      inputSchema: {
+        format: z2.enum(["markdown", "json"]).optional(),
+        output: z2.string().optional()
+      }
+    },
+    async (args) => generated(
+      root,
+      "generate open-questions report",
+      () => generateQuestionsReport(root, { format: args.format, output: args.output })
+    )
+  );
   server.registerTool(
     "kaddo_generate_capsule_draft",
     { title: "Generate capsule draft", description: `Write a capsule DRAFT under .kaddo/exports/ (never registers it). ${DERIVED_NOTE}`, inputSchema: {} },

package/package.json

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