@kaddo/cli 3.32.0 → 3.34.0

package/README.md

@@ -528,6 +528,8 @@ 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 |
+| v3.34 | Pre-AI onboarding: `kaddo onboarding` (alias `onboard`) / `kaddo report onboarding` — read-only diagnosis of an existing project's readiness (scan/understand/knowledge/questions/roadmap/work-items/adapters) with a single recommended next step; `--json` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -704,6 +704,10 @@ var COMMAND_HELP = {
   "adapters install codex": {
     question: "How does Codex work with this Kaddo project?",
     next: "Open AGENTS.md, or regenerate it after knowledge changes"
+  },
+  onboarding: {
+    question: "How ready is this pre-AI project to work with agents?",
+    next: "Run the single recommended next step, then re-run `kaddo onboarding`"
   }
 };
 function commandFooterLines(name) {
@@ -2414,9 +2418,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 +2743,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 +3254,20 @@ 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.
+
+## Pre-AI projects
+
+For **pre-AI** projects (existing code, little structured knowledge), use \`kaddo onboarding\` as the
+compass: it diagnoses the current state and recommends a single next step along the cycle
+\`init \u2192 scan \u2192 understand \u2192 onboarding \u2192 questions \u2192 roadmap \u2192 create --from roadmap \u2192 adapter \u2192
+implement \u2192 guard\`. Use the \`scan\` and \`understand\` outputs as input \u2014 **do not invent project
+goals or capabilities**. Capture unknowns as \`[open]\` questions and safe, explicit defaults as
+\`[assumed]\`. Build \`knowledge/tech/current-state.md\` and \`knowledge/tech/codebase.md\` from real
+repo signals before drafting the roadmap or the first Work Item.
 
 ## When to Use
 
@@ -3361,9 +3383,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 +8231,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 +8340,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 +8384,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 +8423,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 +8453,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 +8472,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 +8570,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 +12353,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 +12520,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 +12644,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`,");
@@ -12828,6 +12905,229 @@ function runAdaptersStatus(opts = {}) {
   }
 }
 
+// src/core/onboarding.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 p2 = join(dir, rel);
+  if (!exists(p2)) return "missing";
+  let md;
+  try {
+    md = readFile(p2);
+  } 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 p2 = join(dir, "knowledge/delivery/roadmap.md");
+  if (!exists(p2)) return "missing";
+  let md;
+  try {
+    md = readFile(p2);
+  } catch {
+    return "missing";
+  }
+  const stripped = md.replace(/^---[\s\S]*?---/m, "");
+  const lines = stripped.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 buildOnboardingReport(dir, now = /* @__PURE__ */ new Date()) {
+  const config = loadConfig(dir);
+  const ts = now.toISOString();
+  const notReady = (status2, label, command) => ({
+    generated_at: ts,
+    project_name: config?.project.name ?? "unknown",
+    project_type: config?.project.state ?? "unknown",
+    status: status2,
+    signals: {
+      scan: "missing",
+      understand: "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 notReady("not-initialized", "Run `kaddo init` to initialize Kaddo.", "kaddo init");
+  if (config.project.state === "new") return notReady("not-applicable", "This guide is optimized for pre-AI projects. Use the standard new-project Kaddo flow.");
+  if (config.project.state === "legacy") return notReady("legacy-project", "Use the legacy project flow. The onboarding guide targets pre-AI projects.");
+  const scan2 = 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 roadmap = roadmapSignal(dir);
+  const work_items = workItemsSignal(dir);
+  const adapters = installedAdapters(dir);
+  const oq = buildOpenQuestionsReport(dir, now);
+  const signals = {
+    scan: scan2,
+    understand,
+    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 status;
+  let next;
+  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "present");
+  if (scan2 === "missing") {
+    status = "initialized";
+    next = { label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan" };
+  } else if (understand === "missing") {
+    status = "scanned";
+    next = { label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand" };
+  } else if (firstWeak) {
+    status = "knowledge-incomplete";
+    next = { label: `Complete \`${firstWeak.label}\` (it is ${presence[firstWeak.key]}).` };
+  } else if (oq.summary.blocking_open > 0) {
+    status = "needs-decisions";
+    next = { label: "Resolve, assume or defer the blocking open questions (`kaddo questions`).", command: "kaddo questions" };
+  } else if (roadmap !== "has-candidates") {
+    status = "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") {
+    status = "ready-for-work-item";
+    next = { label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap" };
+  } else {
+    status = "ready-for-implementation";
+    next = adapters.length > 0 ? { label: "Implement the ready Work Item with an installed adapter, then run `kaddo guard`." } : { label: "Install an adapter, then implement the ready Work Item.", command: "kaddo adapters list" };
+  }
+  return { generated_at: ts, project_name: config.project.name, project_type: config.project.state, status, signals, recommended_next_step: next };
+}
+function serializeOnboardingJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+function renderOnboardingMarkdown(r) {
+  const s = r.signals;
+  const L = [];
+  L.push("# Pre-AI Onboarding Report", "");
+  L.push("## Summary", "");
+  L.push(`- Project: ${r.project_name}`);
+  L.push(`- Project type: ${r.project_type}`);
+  L.push(`- Status: ${r.status}`);
+  L.push("");
+  if (r.status === "not-initialized" || r.status === "not-applicable" || r.status === "legacy-project") {
+    L.push("## Recommended Next Step", "", r.recommended_next_step.label, "");
+    return L.join("\n");
+  }
+  L.push("## Signals", "");
+  L.push(`- Scan: ${s.scan}`);
+  L.push(`- Understand: ${s.understand}`);
+  L.push(`- Current state: ${s.current_state}`);
+  L.push(`- Codebase: ${s.codebase}`);
+  L.push(`- Capabilities: ${s.capabilities}`);
+  L.push(`- Product: ${s.product}`);
+  L.push(`- Business: ${s.business}`);
+  L.push(`- Roadmap: ${s.roadmap}`);
+  L.push(`- Work Items: ${s.work_items}`);
+  L.push(`- Adapters: ${s.adapters.length > 0 ? s.adapters.join(", ") + " installed" : "none installed"}`);
+  L.push("");
+  L.push("## Questions", "");
+  L.push(`- Blocking open: ${s.blocking_open_questions}`);
+  L.push(`- Assumed: ${s.assumed_questions}`);
+  L.push(`- Resolved: ${s.resolved_questions}`);
+  L.push(`- Deferred: ${s.deferred_questions}`);
+  L.push("");
+  L.push("## Recommended Next Step", "", r.recommended_next_step.label, "");
+  return L.join("\n");
+}
+
+// src/commands/onboarding.ts
+function printConsole(r) {
+  const s = r.signals;
+  console.log("");
+  console.log("Pre-AI Onboarding");
+  console.log("");
+  console.log(`Project: ${r.project_name}`);
+  console.log(`Project type: ${r.project_type}`);
+  console.log("");
+  console.log("Status:");
+  console.log(`  overall: ${r.status}`);
+  if (r.status !== "not-initialized" && r.status !== "not-applicable" && r.status !== "legacy-project") {
+    console.log(`  scan: ${s.scan}`);
+    console.log(`  understand: ${s.understand}`);
+    console.log(`  current-state: ${s.current_state}`);
+    console.log(`  codebase: ${s.codebase}`);
+    console.log(`  capabilities: ${s.capabilities}`);
+    console.log(`  roadmap: ${s.roadmap}`);
+    console.log(`  work-items: ${s.work_items}`);
+    console.log(`  adapters: ${s.adapters.length > 0 ? s.adapters.join(", ") + " installed" : "none installed"}`);
+    console.log(`  blocking open questions: ${s.blocking_open_questions}`);
+    console.log(`  assumptions: ${s.assumed_questions}`);
+    console.log(`  deferred: ${s.deferred_questions}`);
+  }
+  console.log("");
+  console.log("Recommended next step:");
+  console.log(`  ${r.recommended_next_step.label}`);
+}
+function runOnboarding(opts = {}) {
+  const dir = cwd();
+  const report = buildOnboardingReport(dir);
+  if (opts.json) {
+    console.log(serializeOnboardingJson(report));
+    return;
+  }
+  printConsole(report);
+  printCommandFooter("onboarding");
+}
+function runOnboardingReport(opts = {}) {
+  const dir = cwd();
+  const report = buildOnboardingReport(dir);
+  if (report.status === "not-initialized") {
+    console.error("Kaddo is not initialized here. Run `kaddo init` first.");
+    return;
+  }
+  intro2("kaddo report onboarding");
+  const base = ".kaddo/reports";
+  writeFile(join(dir, base, "onboarding-report.md"), renderOnboardingMarkdown(report));
+  writeFile(join(dir, base, "onboarding-report.json"), serializeOnboardingJson(report));
+  log2.success(`Wrote ${base}/onboarding-report.md and ${base}/onboarding-report.json`);
+  log2.info(`Status: ${report.status} \u2014 ${report.recommended_next_step.label}`);
+  printCommandFooter("onboarding");
+  outro2("Onboarding report written.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -12875,12 +13175,18 @@ savingsCmd.command("init").description("Create an editable `.kaddo/savings.yml`
 reportCmd.command("drift").description("Drift Trend Report from recorded guard history (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/drift-report.md)").action((opts) => {
   runDrift(opts);
 });
+reportCmd.command("onboarding").description("Write the pre-AI onboarding report to .kaddo/reports/ (deterministic, no LLM)").action(() => {
+  runOnboardingReport();
+});
 program.command("drift").description("Drift Trend Report from recorded `kaddo guard --record` history").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file").action((opts) => {
   runDrift(opts);
 });
 var questionsAction = (opts) => runQuestions(opts);
 program.command("questions").description("Open-questions readiness gate: blocking/important/deferred decisions before the roadmap").option("--json", "Output JSON instead of a summary").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/questions-report.md)").action(questionsAction);
 program.command("readiness").description("Alias for `kaddo questions`").option("--json", "Output JSON instead of a summary").option("--output <path>", "Write the report to a file").action(questionsAction);
+program.command("onboarding").alias("onboard").description("Diagnose a pre-AI project and recommend the next step (read-only)").option("--json", "Output JSON").action((opts) => {
+  runOnboarding(opts);
+});
 var adaptersCmd = program.command("adapters").description("Generate adapters that project Kaddo knowledge for external coding agents");
 adaptersCmd.command("install <adapter>").description("Generate an adapter file (codex/opencode/antigravity/kiro \u2192 AGENTS.md, claude \u2192 CLAUDE.md) from Kaddo knowledge").option("--force", "Overwrite an existing output file").option("--inject", "Add or update only the Kaddo block in an existing file, preserving the rest").option("--dry-run", "Print the content without writing files").action((adapter, opts) => {
   runAdaptersInstall(adapter, opts);

package/package.json

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