@kaddo/mcp 3.33.0 → 3.35.0

package/dist/index.js

@@ -1683,6 +1683,572 @@ function roadmapStats(markdown, materialized) {
   return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
 }
 
+// ../cli/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",
+  "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 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 raw = m[1].trim();
+      if (!raw || /^_.*_$/.test(raw)) continue;
+      const { text: text2, resolution_status } = parseResolution(raw);
+      if (text2) out.push({ text: text2, resolution_status });
+    }
+  }
+  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 eq of extractFromMarkdown(md)) {
+      seq += 1;
+      const { classification, reason } = classifyQuestion(eq.text);
+      questions.push({
+        id: `OQ-${String(seq).padStart(3, "0")}`,
+        source,
+        section: "Open Questions",
+        question: eq.text,
+        classification,
+        resolution_status: eq.resolution_status,
+        reason,
+        ...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 (blockingOpen.length > 0) readiness = "needs_decisions";
+  else readiness = "ready";
+  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,
+    summary: {
+      open_questions: questions.length,
+      roadmap_readiness: readiness,
+      blocking: blocking.length,
+      important: important.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
+  };
+}
+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(`- 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");
+  }
+  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}`);
+    L.push(`- Reason: ${q.reason}`);
+    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.resolution_status}] ${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,
+    blocking_open: r.summary.blocking_open,
+    important_questions: r.summary.important,
+    deferred_questions: r.summary.deferred,
+    resolution: r.summary.resolution,
+    suggested_assumptions: r.suggested_assumptions,
+    recommended_next_step: r.summary.roadmap_readiness === "needs_decisions" ? "Resolve, assume, or defer blocking open questions before generating roadmap." : r.recommended_next_step
+  };
+}
+
+// ../cli/src/core/codex-adapter.ts
+var KNOWLEDGE_PATHS = [
+  "knowledge/business/",
+  "knowledge/product/",
+  "knowledge/tech/",
+  "knowledge/delivery/",
+  "knowledge/agents/",
+  "knowledge/skills/"
+];
+var GENERATED_PATHS = [
+  ".kaddo/context-pack.md",
+  ".kaddo/understand.md",
+  ".kaddo/explain.md",
+  ".kaddo/graph.json",
+  ".kaddo/reports/"
+];
+function discoverAgents(dir) {
+  const base = join(dir, "knowledge", "agents");
+  if (!exists(base) || !isDir(base)) return [];
+  const out = /* @__PURE__ */ new Set();
+  const walk = (d) => {
+    for (const e of readDir(d)) {
+      const full = join(d, e);
+      if (isDir(full)) walk(full);
+      else if (e.endsWith("-agent.md")) out.add(e.replace(/\.md$/, ""));
+    }
+  };
+  walk(base);
+  return [...out].sort();
+}
+function buildCodexAdapterContext(dir) {
+  const config = loadConfig(dir);
+  const agents = discoverAgents(dir);
+  const skills = discoverInstalledSkills(dir).map((s) => s.id);
+  return {
+    projectName: config?.project.name,
+    projectType: config?.project.state,
+    language: config ? config.project.language : void 0,
+    packageManager: detectPackageManager(dir),
+    hasAgents: agents.length > 0,
+    agents,
+    hasSkills: skills.length > 0,
+    skills,
+    hasMcpHint: detectMcpHint(dir),
+    knowledgePaths: KNOWLEDGE_PATHS.filter((p) => exists(join(dir, p))),
+    generatedPaths: GENERATED_PATHS
+  };
+}
+function detectPackageManager(dir) {
+  if (exists(join(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (exists(join(dir, "yarn.lock"))) return "yarn";
+  if (exists(join(dir, "bun.lockb")) || exists(join(dir, "bun.lock"))) return "bun";
+  if (exists(join(dir, "package-lock.json"))) return "npm";
+  return void 0;
+}
+function detectMcpHint(dir) {
+  for (const f of [".mcp.json", "mcp.json", ".cursor/mcp.json"]) {
+    if (exists(join(dir, f))) return true;
+  }
+  return false;
+}
+var KADDO_BEGIN_MARKER = "<!-- BEGIN KADDO ADAPTER -->";
+var KADDO_END_MARKER = "<!-- END KADDO ADAPTER -->";
+var LEGACY_BEGIN_MARKER = "<!-- BEGIN KADDO CODEX ADAPTER -->";
+var LEGACY_END_MARKER = "<!-- END KADDO CODEX ADAPTER -->";
+var GENERATED_HEADER = "Generated by `kaddo adapters install ";
+function detectAgentsState(content) {
+  if (content === null) return "missing";
+  const hasBegin = content.includes(KADDO_BEGIN_MARKER) || content.includes(LEGACY_BEGIN_MARKER);
+  const hasEnd = content.includes(KADDO_END_MARKER) || content.includes(LEGACY_END_MARKER);
+  if (hasBegin !== hasEnd) return "invalid_kaddo_block";
+  if (hasBegin && hasEnd) return "existing_with_kaddo_block";
+  if (content.includes(GENERATED_HEADER)) return "generated_by_kaddo";
+  return "existing_external";
+}
+var ADAPTERS = [
+  { id: "codex", label: "Codex", file: "AGENTS.md", supportsInject: true },
+  { id: "claude", label: "Claude Code", file: "CLAUDE.md", supportsInject: true },
+  { id: "opencode", label: "OpenCode", file: "AGENTS.md", supportsInject: true },
+  { id: "antigravity", label: "Antigravity", file: "AGENTS.md", supportsInject: true },
+  { id: "kiro", label: "Kiro", file: "AGENTS.md", supportsInject: true }
+];
+function findAdapter(id) {
+  return ADAPTERS.find((a) => a.id === id);
+}
+function parseOriginAdapter(content) {
+  const m = content.match(/Generated by `kaddo adapters install (\w+)`/);
+  const id = m?.[1];
+  return id && findAdapter(id) ? id : null;
+}
+function classifyAdapterState(content) {
+  const base = detectAgentsState(content);
+  switch (base) {
+    case "missing":
+      return "missing";
+    case "invalid_kaddo_block":
+      return "broken-markers";
+    case "generated_by_kaddo":
+      return "full-generated";
+    case "existing_with_kaddo_block":
+      return content.includes(LEGACY_BEGIN_MARKER) ? "legacy-injected" : "injected";
+    default:
+      return "team-owned";
+  }
+}
+function recommendedAction(a, state) {
+  const cmd = `kaddo adapters install ${a.id}`;
+  switch (state) {
+    case "missing":
+      return cmd;
+    case "team-owned":
+      return `${cmd} --inject`;
+    case "injected":
+      return "No action needed (run --inject to update the Kaddo block).";
+    case "legacy-injected":
+      return `${cmd} --inject (migrates legacy markers to neutral)`;
+    case "full-generated":
+      return `No action needed. Use \`${cmd} --force\` only to regenerate for ${a.label}.`;
+    case "broken-markers":
+      return "Fix the incomplete Kaddo adapter markers before running --inject.";
+  }
+}
+function buildAdapterStatuses(dir) {
+  const cache = /* @__PURE__ */ new Map();
+  const read = (file) => {
+    if (!cache.has(file)) {
+      const full = join(dir, file);
+      cache.set(file, exists(full) ? readFile(full) : null);
+    }
+    return cache.get(file);
+  };
+  return ADAPTERS.map((a) => {
+    const content = read(a.file);
+    const state = classifyAdapterState(content);
+    const originAdapter = content ? parseOriginAdapter(content) : null;
+    return { ...a, state, originAdapter, recommendedAction: recommendedAction(a, state) };
+  });
+}
+
+// ../cli/src/core/readiness.ts
+var KNOWLEDGE_FILES = [
+  { key: "current_state", path: "knowledge/tech/current-state.md", label: "knowledge/tech/current-state.md" },
+  { key: "codebase", path: "knowledge/tech/codebase.md", label: "knowledge/tech/codebase.md" },
+  { key: "capabilities", path: "knowledge/product/capabilities.md", label: "knowledge/product/capabilities.md" },
+  { key: "product", path: "knowledge/product/product.md", label: "knowledge/product/product.md" },
+  { key: "business", path: "knowledge/business/business.md", label: "knowledge/business/business.md" }
+];
+function knowledgePresence(dir, rel) {
+  const p = join(dir, rel);
+  if (!exists(p)) return "missing";
+  let md;
+  try {
+    md = readFile(p);
+  } catch {
+    return "missing";
+  }
+  const body = md.replace(/^---[\s\S]*?---/m, "").split(/\r?\n/).filter((l) => !/^\s*#{1,6}\s/.test(l) && !/^\s*$/.test(l) && !/^\s*<!--/.test(l)).join(" ").trim();
+  return body.length >= 40 ? "present" : "weak";
+}
+function roadmapSignal(dir) {
+  const p = join(dir, "knowledge/delivery/roadmap.md");
+  if (!exists(p)) return "missing";
+  let md;
+  try {
+    md = readFile(p);
+  } catch {
+    return "missing";
+  }
+  const lines = md.replace(/^---[\s\S]*?---/m, "").split(/\r?\n/);
+  let inOpenQuestions = false;
+  let candidates = 0;
+  for (const l of lines) {
+    if (/^#{1,6}\s/.test(l)) inOpenQuestions = /open questions|preguntas abiertas/i.test(l);
+    else if (!inOpenQuestions && /^\s*(?:[-*]\s+|\|)/.test(l)) candidates += 1;
+  }
+  return candidates > 0 ? "has-candidates" : "empty";
+}
+function workItemsSignal(dir) {
+  const wis = discoverWorkItems(dir);
+  if (wis.length === 0) return "none";
+  if (wis.some((w) => w.lifecycle === "in-progress")) return "in-progress";
+  if (wis.some((w) => w.lifecycle === "ready")) return "ready";
+  return "none-ready";
+}
+function installedAdapters(dir) {
+  return buildAdapterStatuses(dir).filter(
+    (s) => s.state === "injected" || s.state === "legacy-injected" || s.state === "full-generated" && (s.originAdapter === s.id || s.originAdapter === null)
+  ).map((s) => s.id);
+}
+function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
+  const config = loadConfig(dir);
+  const stub = (overall2, label, command) => ({
+    project_name: config?.project.name ?? "unknown",
+    project_type: config?.project.state ?? "unknown",
+    overall: overall2,
+    signals: {
+      scan: "missing",
+      understand: "missing",
+      bootstrap_baseline: "incomplete",
+      agents: "missing",
+      skills: "missing",
+      current_state: "missing",
+      codebase: "missing",
+      capabilities: "missing",
+      product: "missing",
+      business: "missing",
+      roadmap: "missing",
+      work_items: "none",
+      adapters: [],
+      blocking_open_questions: 0,
+      assumed_questions: 0,
+      resolved_questions: 0,
+      deferred_questions: 0
+    },
+    recommended_next_step: { label, ...command ? { command } : {} }
+  });
+  if (!config) return stub("not-initialized", "Run `kaddo init` to initialize Kaddo.", "kaddo init");
+  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";
+  const understand = exists(join(dir, ".kaddo", "understand.md")) ? "available" : "missing";
+  const presence = Object.fromEntries(KNOWLEDGE_FILES.map((f) => [f.key, knowledgePresence(dir, f.path)]));
+  const ctx = buildCodexAdapterContext(dir);
+  const agents = ctx.hasAgents ? "present" : "missing";
+  const skills = ctx.hasSkills ? "present" : "missing";
+  const bootstrapBaseline = presence.business !== "missing" && presence.product !== "missing" ? "complete" : "incomplete";
+  const roadmap = roadmapSignal(dir);
+  const work_items = workItemsSignal(dir);
+  const adapters = installedAdapters(dir);
+  const oq = buildOpenQuestionsReport(dir, now);
+  const signals = {
+    scan,
+    understand,
+    bootstrap_baseline: bootstrapBaseline,
+    agents,
+    skills,
+    current_state: presence.current_state,
+    codebase: presence.codebase,
+    capabilities: presence.capabilities,
+    product: presence.product,
+    business: presence.business,
+    roadmap,
+    work_items,
+    adapters,
+    blocking_open_questions: oq.summary.blocking_open,
+    assumed_questions: oq.summary.resolution.assumed,
+    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] !== "present");
+  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: `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 };
+}
+
 // ../cli/src/core/project-explain.ts
 var ARCH_DIR2 = "knowledge";
 function normalizeTitle(t) {
@@ -1891,7 +2457,8 @@ function buildProjectExplanation(dir) {
     roadmap,
     mappedModules,
     missingKnowledge,
-    suggestedNextSteps
+    suggestedNextSteps,
+    readiness: buildReadinessReport(dir)
   };
 }
 function stateLabel(state) {
@@ -1959,8 +2526,8 @@ function renderExplanationHuman(exp) {
   lines.push("");
   if (exp.workItems.total > 0) {
     lines.push("## Work Items");
-    for (const s of LIFECYCLE_STATES) {
-      lines.push(`- ${LIFECYCLE_LABEL[s]}: ${exp.workItems.byState[s]}`);
+    for (const s2 of LIFECYCLE_STATES) {
+      lines.push(`- ${LIFECYCLE_LABEL[s2]}: ${exp.workItems.byState[s2]}`);
     }
     lines.push("");
     const typeEntries = Object.entries(exp.workItems.byType).sort((a, b) => b[1] - a[1]);
@@ -1970,13 +2537,13 @@ function renderExplanationHuman(exp) {
       lines.push("");
     }
     const grouped = exp.workItems.initiatives.filter(
-      (g) => LIFECYCLE_STATES.some((s) => g.states[s] > 0)
+      (g) => LIFECYCLE_STATES.some((s2) => g.states[s2] > 0)
     );
     if (grouped.length > 0) {
       lines.push("## Work Items by Initiative");
       for (const g of grouped) {
-        const parts = LIFECYCLE_STATES.filter((s) => g.states[s] > 0).map(
-          (s) => `${LIFECYCLE_LABEL[s]}: ${g.states[s]}`
+        const parts = LIFECYCLE_STATES.filter((s2) => g.states[s2] > 0).map(
+          (s2) => `${LIFECYCLE_LABEL[s2]}: ${g.states[s2]}`
         );
         lines.push(`- ${g.name} \u2014 ${parts.join(" \xB7 ")}`);
       }
@@ -2070,15 +2637,39 @@ function renderExplanationHuman(exp) {
   lines.push(`- Phase: ${assessment.phase}`);
   if (assessment.reasons.length > 0) {
     lines.push("- Reason:");
-    for (const r of assessment.reasons) lines.push(`  - ${r}`);
+    for (const r2 of assessment.reasons) lines.push(`  - ${r2}`);
   }
   if (assessment.nextStep) lines.push(`- Next step: ${assessment.nextStep}`);
   lines.push("");
   if (exp.suggestedNextSteps.length > 0) {
     lines.push("## Suggested Next Steps");
-    exp.suggestedNextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    exp.suggestedNextSteps.forEach((s2, i) => lines.push(`${i + 1}. ${s2}`));
     lines.push("");
   }
+  const r = exp.readiness;
+  const s = r.signals;
+  lines.push("## Project Readiness");
+  lines.push(`- overall: ${r.overall}`);
+  if (r.overall !== "not-initialized" && r.overall !== "not-applicable" && r.overall !== "legacy-project") {
+    lines.push(`- bootstrap baseline: ${s.bootstrap_baseline}`);
+    lines.push(`- scan: ${s.scan}`);
+    lines.push(`- understand: ${s.understand}`);
+    lines.push(`- agents: ${s.agents}`);
+    lines.push(`- skills: ${s.skills}`);
+    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"}`);
+    lines.push(`- blocking open questions: ${s.blocking_open_questions}`);
+    lines.push(`- assumptions: ${s.assumed_questions}`);
+    lines.push(`- deferred: ${s.deferred_questions}`);
+  }
+  lines.push("");
+  lines.push("### Recommended next step");
+  lines.push(r.recommended_next_step.label);
+  lines.push("");
   return lines.join("\n").trimEnd() + "\n";
 }
 function renderExplanationAgent(exp) {
@@ -2776,498 +3367,218 @@ function buildSavingsReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       ownership_coverage_percent: impact.ownership_coverage.coverage_percent,
       work_items_with_acceptance_criteria: acceptanceCov ? `${acceptanceCov.have}/${acceptanceCov.total}` : "0/0",
       graph_quality: graphQuality,
-      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_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` },
-      review_effort: { hours: reviewH, formula: `${wiWithOwnership} Work Items with ownership \xD7 ${a.review_minutes_saved_per_work_item_with_ownership} min` },
-      clarification_reduction: { hours: clarH, formula: `${wiWithAcceptance} Work Items with Acceptance Criteria \xD7 ${a.clarification_minutes_saved_per_ready_work_item} min` },
-      onboarding: { hours: onboardH, formula: `${a.expected_new_contributors_per_month} contributor \xD7 ${a.onboarding_hours_saved_per_new_contributor} h \xD7 ${readinessMult.toFixed(2)} readiness multiplier` },
-      architecture_discovery: { hours: archH, formula: `${a.architecture_discovery_hours_saved_when_graph_good} h \xD7 ${graphMult.toFixed(2)} graph multiplier` },
-      drift_prevention: driftSavings
-    },
-    total: { estimated_hours_saved: totalHours, estimated_value: totalValue, currency: a.currency },
-    confidence: { level, reasons },
-    suggested_actions: actions
-  };
-}
-function renderSavingsMarkdown(r) {
-  const L = [];
-  L.push("# Kaddo Estimated Savings Report", "");
-  L.push(`Generated at: ${r.generated_at}`);
-  L.push(`Project: ${r.project}`);
-  L.push(`Scope: ${r.scope}`);
-  L.push(`Currency: ${r.currency}`);
-  L.push("");
-  L.push("## Disclaimer", "");
-  L.push(r.disclaimer, "");
-  L.push("## Executive Summary", "");
-  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} hours`);
-  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
-  L.push(`- Confidence: ${r.confidence.level}`);
-  if (r.assumptions_source === "default") L.push("- Using default assumptions. Run `kaddo savings init` to customize them.");
-  L.push("");
-  L.push("## Assumptions", "");
-  L.push(`- Hourly cost: ${r.assumptions.hourly_cost} ${r.currency}`);
-  L.push(`- Context preparation saved per Work Item: ${r.assumptions.context_preparation_minutes_saved_per_work_item} min`);
-  L.push(`- Review saved per Work Item with ownership: ${r.assumptions.review_minutes_saved_per_work_item_with_ownership} min`);
-  L.push(`- Clarification saved per Work Item with acceptance criteria: ${r.assumptions.clarification_minutes_saved_per_ready_work_item} min`);
-  L.push(`- Onboarding saved per new contributor: ${r.assumptions.onboarding_hours_saved_per_new_contributor} h`);
-  L.push(`- Expected new contributors per month: ${r.assumptions.expected_new_contributors_per_month}`);
-  L.push(`- Architecture discovery saved when graph is good: ${r.assumptions.architecture_discovery_hours_saved_when_graph_good} h`);
-  L.push("");
-  L.push("## Evidence Used", "");
-  const e = r.evidence;
-  L.push(`- Knowledge Impact Score: ${e.knowledge_impact_score ?? "not available"}${e.knowledge_impact_score !== null ? "/100" : ""}`);
-  L.push(`- Completed Work Items: ${e.completed_work_items}`);
-  L.push(`- Ownership coverage: ${e.ownership_coverage_percent}%`);
-  L.push(`- Work Items with Acceptance Criteria: ${e.work_items_with_acceptance_criteria}`);
-  L.push(`- Graph quality: ${e.graph_quality}`);
-  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}`);
-  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;
-  const line = (title, l) => {
-    L.push(`### ${title}`, "");
-    L.push(`- Formula: ${l.formula}`);
-    L.push(`- Estimated: ${l.hours} h`, "");
-  };
-  line("Context Preparation", s.context_preparation);
-  line("Review Effort", s.review_effort);
-  line("Clarification Reduction", s.clarification_reduction);
-  line("Onboarding", s.onboarding);
-  line("Architecture Discovery", s.architecture_discovery);
-  L.push("### Drift Prevention", "");
-  if (s.drift_prevention.available) {
-    L.push(`- Formula: ${s.drift_prevention.formula}`);
-    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}`, "");
-  }
-  L.push("## Total", "");
-  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} h`);
-  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
-  L.push("");
-  L.push("## Confidence", "");
-  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
-  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
-  L.push("");
-  L.push("## Suggested Actions", "");
-  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
-  L.push("");
-  return L.join("\n");
-}
-function serializeSavingsJson(r) {
-  return JSON.stringify(r, null, 2) + "\n";
-}
-
-// ../cli/src/core/drift-report.ts
-function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
-  const h = buildGuardHistory(dir);
-  const project = loadConfig(dir)?.project.name ?? "unknown";
-  const actions = [];
-  if (!h.available) {
-    actions.push("Run `kaddo guard --record` to start recording guard history.");
-  } else {
-    if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
-    actions.push("Run `kaddo guard --record` before important commits.");
-    actions.push("Use this report to calibrate estimated drift-prevention savings.");
-  }
-  return {
-    generated_at: now.toISOString(),
-    project,
-    guard_history: {
-      available: h.available,
-      total_runs: h.total_runs,
-      first_run: h.first_run,
-      last_run: h.last_run,
-      runs_with_warnings: h.runs_with_warnings,
-      runs_clean: h.runs_clean
+      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_runs_recorded: guard.total_runs,
+      resolved_drift_warnings: guard.resolved
     },
-    drift_warnings: { detected: h.detected, open: h.open, resolved: h.resolved, resolution_rate: h.resolution_rate },
-    hotspots: h.hotspots,
-    trend: h.trend,
-    threads: h.threads,
+    estimated_savings: {
+      context_preparation: { hours: ctxPrepH, formula: `${completed} Work Items \xD7 ${a.context_preparation_minutes_saved_per_work_item} min` },
+      review_effort: { hours: reviewH, formula: `${wiWithOwnership} Work Items with ownership \xD7 ${a.review_minutes_saved_per_work_item_with_ownership} min` },
+      clarification_reduction: { hours: clarH, formula: `${wiWithAcceptance} Work Items with Acceptance Criteria \xD7 ${a.clarification_minutes_saved_per_ready_work_item} min` },
+      onboarding: { hours: onboardH, formula: `${a.expected_new_contributors_per_month} contributor \xD7 ${a.onboarding_hours_saved_per_new_contributor} h \xD7 ${readinessMult.toFixed(2)} readiness multiplier` },
+      architecture_discovery: { hours: archH, formula: `${a.architecture_discovery_hours_saved_when_graph_good} h \xD7 ${graphMult.toFixed(2)} graph multiplier` },
+      drift_prevention: driftSavings
+    },
+    total: { estimated_hours_saved: totalHours, estimated_value: totalValue, currency: a.currency },
+    confidence: { level, reasons },
     suggested_actions: actions
   };
 }
-function renderDriftMarkdown(r) {
+function renderSavingsMarkdown(r) {
   const L = [];
-  L.push("# Kaddo Drift Trend Report", "");
+  L.push("# Kaddo Estimated Savings Report", "");
   L.push(`Generated at: ${r.generated_at}`);
   L.push(`Project: ${r.project}`);
+  L.push(`Scope: ${r.scope}`);
+  L.push(`Currency: ${r.currency}`);
   L.push("");
-  if (!r.guard_history.available) {
-    L.push("## Guard History", "");
-    L.push("No guard history recorded yet.");
-    L.push("");
-    L.push("Run `kaddo guard --record` to start recording drift evidence.");
-    L.push("");
-    L.push("## Suggested Actions", "");
-    r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
-    L.push("");
-    return L.join("\n");
-  }
-  const w = r.drift_warnings;
+  L.push("## Disclaimer", "");
+  L.push(r.disclaimer, "");
   L.push("## Executive Summary", "");
-  L.push(`- Guard runs recorded: ${r.guard_history.total_runs}`);
-  L.push(`- Drift warnings detected: ${w.detected}`);
-  L.push(`- Open warnings: ${w.open}`);
-  L.push(`- Resolved warnings: ${w.resolved}`);
-  L.push(`- Resolution rate: ${w.resolution_rate}%`);
-  if (r.hotspots.length > 0) L.push(`- Most affected area: ${r.hotspots[0].path}`);
-  L.push("");
-  L.push("## Guard History", "");
-  L.push(`- First run: ${r.guard_history.first_run}`);
-  L.push(`- Last run: ${r.guard_history.last_run}`);
-  L.push(`- Runs with warnings: ${r.guard_history.runs_with_warnings}/${r.guard_history.total_runs}`);
-  L.push(`- Runs clean: ${r.guard_history.runs_clean}/${r.guard_history.total_runs}`);
-  L.push("");
-  L.push("## Drift Warnings", "");
-  const open = r.threads.filter((t) => t.status === "open");
-  const resolved = r.threads.filter((t) => t.status === "resolved");
-  L.push("### Open", "");
-  if (open.length === 0) L.push("_None._", "");
-  for (const t of open) {
-    L.push(`- ${t.code_path}`);
-    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
-    L.push(`  - First detected: ${t.first_detected}`);
-    L.push(`  - Last seen: ${t.last_seen}`);
-    L.push("  - Status: open");
-  }
-  L.push("");
-  L.push("### Resolved", "");
-  if (resolved.length === 0) L.push("_None._", "");
-  for (const t of resolved) {
-    L.push(`- ${t.code_path}`);
-    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
-    L.push(`  - First detected: ${t.first_detected}`);
-    L.push(`  - Resolved at: ${t.resolved_at}`);
-    L.push("  - Status: resolved");
-  }
-  L.push("");
-  L.push("## Hotspots", "");
-  if (r.hotspots.length === 0) L.push("_None._");
-  for (const h of r.hotspots) L.push(`- ${h.path}: ${h.warnings} warning(s)`);
-  L.push("");
-  L.push("## Trend", "");
-  L.push(`- Recent direction: ${r.trend.direction}`);
-  L.push(`- Reason: ${r.trend.reason}`);
+  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} hours`);
+  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
+  L.push(`- Confidence: ${r.confidence.level}`);
+  if (r.assumptions_source === "default") L.push("- Using default assumptions. Run `kaddo savings init` to customize them.");
   L.push("");
-  L.push("## Suggested Actions", "");
-  r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+  L.push("## Assumptions", "");
+  L.push(`- Hourly cost: ${r.assumptions.hourly_cost} ${r.currency}`);
+  L.push(`- Context preparation saved per Work Item: ${r.assumptions.context_preparation_minutes_saved_per_work_item} min`);
+  L.push(`- Review saved per Work Item with ownership: ${r.assumptions.review_minutes_saved_per_work_item_with_ownership} min`);
+  L.push(`- Clarification saved per Work Item with acceptance criteria: ${r.assumptions.clarification_minutes_saved_per_ready_work_item} min`);
+  L.push(`- Onboarding saved per new contributor: ${r.assumptions.onboarding_hours_saved_per_new_contributor} h`);
+  L.push(`- Expected new contributors per month: ${r.assumptions.expected_new_contributors_per_month}`);
+  L.push(`- Architecture discovery saved when graph is good: ${r.assumptions.architecture_discovery_hours_saved_when_graph_good} h`);
   L.push("");
-  return L.join("\n");
-}
-function serializeDriftJson(r) {
-  const out = {
-    generated_at: r.generated_at,
-    project: r.project,
-    guard_history: r.guard_history,
-    drift_warnings: r.drift_warnings,
-    hotspots: r.hotspots,
-    trend: r.trend,
-    threads: r.threads,
-    suggested_actions: r.suggested_actions
-  };
-  return JSON.stringify(out, null, 2) + "\n";
-}
-
-// ../cli/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",
-  "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 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 raw = m[1].trim();
-      if (!raw || /^_.*_$/.test(raw)) continue;
-      const { text: text2, resolution_status } = parseResolution(raw);
-      if (text2) out.push({ text: text2, resolution_status });
-    }
-  }
-  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.";
+  L.push("## Evidence Used", "");
+  const e = r.evidence;
+  L.push(`- Knowledge Impact Score: ${e.knowledge_impact_score ?? "not available"}${e.knowledge_impact_score !== null ? "/100" : ""}`);
+  L.push(`- Completed Work Items: ${e.completed_work_items}`);
+  L.push(`- Ownership coverage: ${e.ownership_coverage_percent}%`);
+  L.push(`- Work Items with Acceptance Criteria: ${e.work_items_with_acceptance_criteria}`);
+  L.push(`- Graph quality: ${e.graph_quality}`);
+  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}`);
+  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");
   }
-  if (matchesAny(t, ["persist", "base de datos", "database"])) {
-    return "Use a simple local datastore (e.g. SQLite) for the MVP.";
+  L.push("");
+  L.push("## Estimated Savings", "");
+  const s = r.estimated_savings;
+  const line = (title, l) => {
+    L.push(`### ${title}`, "");
+    L.push(`- Formula: ${l.formula}`);
+    L.push(`- Estimated: ${l.hours} h`, "");
+  };
+  line("Context Preparation", s.context_preparation);
+  line("Review Effort", s.review_effort);
+  line("Clarification Reduction", s.clarification_reduction);
+  line("Onboarding", s.onboarding);
+  line("Architecture Discovery", s.architecture_discovery);
+  L.push("### Drift Prevention", "");
+  if (s.drift_prevention.available) {
+    L.push(`- Formula: ${s.drift_prevention.formula}`);
+    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}`, "");
   }
-  return "Proceed with the smallest reasonable MVP interpretation and revisit later.";
+  L.push("## Total", "");
+  L.push(`- Estimated time saved: ${r.total.estimated_hours_saved} h`);
+  L.push(`- Estimated value: ${r.total.estimated_value} ${r.currency}`);
+  L.push("");
+  L.push("## Confidence", "");
+  L.push(`Confidence: ${r.confidence.level}`, "", "Reason:");
+  for (const reason of r.confidence.reasons) L.push(`- ${reason}`);
+  L.push("");
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((act, i) => L.push(`${i + 1}. ${act}`));
+  L.push("");
+  return L.join("\n");
 }
-function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
+function serializeSavingsJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+
+// ../cli/src/core/drift-report.ts
+function buildDriftReport(dir, now = /* @__PURE__ */ new Date()) {
+  const h = buildGuardHistory(dir);
   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 eq of extractFromMarkdown(md)) {
-      seq += 1;
-      const { classification, reason } = classifyQuestion(eq.text);
-      questions.push({
-        id: `OQ-${String(seq).padStart(3, "0")}`,
-        source,
-        section: "Open Questions",
-        question: eq.text,
-        classification,
-        resolution_status: eq.resolution_status,
-        reason,
-        ...eq.resolution_note ? { resolution_note: eq.resolution_note } : {},
-        ...classification === "blocking" && eq.resolution_status === "open" ? { suggested_assumption: suggestedAssumption(eq.text) } : {}
-      });
-    }
+  const actions = [];
+  if (!h.available) {
+    actions.push("Run `kaddo guard --record` to start recording guard history.");
+  } else {
+    if (h.open > 0) actions.push("Review open drift warnings and update related Work Items or ownership.");
+    actions.push("Run `kaddo guard --record` before important commits.");
+    actions.push("Use this report to calibrate estimated drift-prevention savings.");
   }
-  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 (blockingOpen.length > 0) readiness = "needs_decisions";
-  else readiness = "ready";
-  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,
-    summary: {
-      open_questions: questions.length,
-      roadmap_readiness: readiness,
-      blocking: blocking.length,
-      important: important.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
-      }
+    guard_history: {
+      available: h.available,
+      total_runs: h.total_runs,
+      first_run: h.first_run,
+      last_run: h.last_run,
+      runs_with_warnings: h.runs_with_warnings,
+      runs_clean: h.runs_clean
     },
-    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
+    drift_warnings: { detected: h.detected, open: h.open, resolved: h.resolved, resolution_rate: h.resolution_rate },
+    hotspots: h.hotspots,
+    trend: h.trend,
+    threads: h.threads,
+    suggested_actions: actions
   };
 }
-function renderOpenQuestionsMarkdown(r) {
+function renderDriftMarkdown(r) {
   const L = [];
-  L.push("# Kaddo Open Questions Readiness Report", "");
+  L.push("# Kaddo Drift Trend 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(`- 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, "");
+  if (!r.guard_history.available) {
+    L.push("## Guard History", "");
+    L.push("No guard history recorded yet.");
+    L.push("");
+    L.push("Run `kaddo guard --record` to start recording drift evidence.");
+    L.push("");
+    L.push("## Suggested Actions", "");
+    r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+    L.push("");
     return L.join("\n");
   }
-  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}`);
-    L.push(`- Reason: ${q.reason}`);
-    if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
-    L.push("");
+  const w = r.drift_warnings;
+  L.push("## Executive Summary", "");
+  L.push(`- Guard runs recorded: ${r.guard_history.total_runs}`);
+  L.push(`- Drift warnings detected: ${w.detected}`);
+  L.push(`- Open warnings: ${w.open}`);
+  L.push(`- Resolved warnings: ${w.resolved}`);
+  L.push(`- Resolution rate: ${w.resolution_rate}%`);
+  if (r.hotspots.length > 0) L.push(`- Most affected area: ${r.hotspots[0].path}`);
+  L.push("");
+  L.push("## Guard History", "");
+  L.push(`- First run: ${r.guard_history.first_run}`);
+  L.push(`- Last run: ${r.guard_history.last_run}`);
+  L.push(`- Runs with warnings: ${r.guard_history.runs_with_warnings}/${r.guard_history.total_runs}`);
+  L.push(`- Runs clean: ${r.guard_history.runs_clean}/${r.guard_history.total_runs}`);
+  L.push("");
+  L.push("## Drift Warnings", "");
+  const open = r.threads.filter((t) => t.status === "open");
+  const resolved = r.threads.filter((t) => t.status === "resolved");
+  L.push("### Open", "");
+  if (open.length === 0) L.push("_None._", "");
+  for (const t of open) {
+    L.push(`- ${t.code_path}`);
+    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
+    L.push(`  - First detected: ${t.first_detected}`);
+    L.push(`  - Last seen: ${t.last_seen}`);
+    L.push("  - Status: open");
   }
-  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.resolution_status}] ${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("### Resolved", "");
+  if (resolved.length === 0) L.push("_None._", "");
+  for (const t of resolved) {
+    L.push(`- ${t.code_path}`);
+    L.push(`  - Related artifacts: ${t.related_artifacts.join(", ") || "\u2014"}`);
+    L.push(`  - First detected: ${t.first_detected}`);
+    L.push(`  - Resolved at: ${t.resolved_at}`);
+    L.push("  - Status: resolved");
   }
-  L.push("## Recommended Next Step", "", r.recommended_next_step, "");
+  L.push("");
+  L.push("## Hotspots", "");
+  if (r.hotspots.length === 0) L.push("_None._");
+  for (const h of r.hotspots) L.push(`- ${h.path}: ${h.warnings} warning(s)`);
+  L.push("");
+  L.push("## Trend", "");
+  L.push(`- Recent direction: ${r.trend.direction}`);
+  L.push(`- Reason: ${r.trend.reason}`);
+  L.push("");
+  L.push("## Suggested Actions", "");
+  r.suggested_actions.forEach((a, i) => L.push(`${i + 1}. ${a}`));
+  L.push("");
   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,
-    blocking_open: r.summary.blocking_open,
-    important_questions: r.summary.important,
-    deferred_questions: r.summary.deferred,
-    resolution: r.summary.resolution,
-    suggested_assumptions: r.suggested_assumptions,
-    recommended_next_step: r.summary.roadmap_readiness === "needs_decisions" ? "Resolve, assume, or defer blocking open questions before generating roadmap." : r.recommended_next_step
+function serializeDriftJson(r) {
+  const out = {
+    generated_at: r.generated_at,
+    project: r.project,
+    guard_history: r.guard_history,
+    drift_warnings: r.drift_warnings,
+    hotspots: r.hotspots,
+    trend: r.trend,
+    threads: r.threads,
+    suggested_actions: r.suggested_actions
   };
+  return JSON.stringify(out, null, 2) + "\n";
 }
 
 // src/workitems.ts

package/package.json

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