@kaddo/cli 3.37.1 → 3.39.0

package/README.md

@@ -534,6 +534,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.36 | State-aware bootstrap: `kaddo bootstrap` creates the full knowledge baseline for any `project.state` (new/pre-ai/legacy) with state-specific templates — no more new-only warning; idempotent, never overwrites, ensures `tech/decisions/` and `delivery/work-items/` |
 | v3.37 | Placeholder-aware readiness: knowledge files are classified missing/placeholder/weak/useful; a bootstrap file isn't treated as ready knowledge. Layers downgrade to Placeholder/Weak, a new Knowledge Refinement phase recommends the right agent, and `create --from roadmap` is never suggested with 0 candidates |
 | v3.37.1 | Unified next-step: one shared resolver (`core/next-step.ts`) powers `context`, `understand` and `explain` (Phase + Readiness) so they never diverge; agent JSON exposes `nextStepRecommendation`. Fixes duplicate `capabilities` line in explain |
+| v3.38 | Open-question source locations: `kaddo questions` shows each question's `Source` (path:line), `Status`, `Severity`, `Note` + a copy/paste resolution example and localized how-to-resolve guide; JSON/report/MCP carry `sourcePath`, `line`, `raw`, `note` |
+| v3.39 | Existing capability discovery: state-aware `capabilities.md` (pre-ai/legacy = evidence-backed Capability Inventory + Gaps + Roadmap Candidate Signals; legacy adds criticality/change-risk/modernization); capability-agent discovers with evidence, roadmap-agent treats capabilities as primary source |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -2207,6 +2207,32 @@ kaddo context
 Especially useful for pre-AI projects, legacy projects, existing codebases with little
 documentation, and projects where capabilities are not explicitly documented.
 
+## State-aware modes (VS-074)
+
+Adapt to \`project.state\` (from \`.kaddo/config.yml\`):
+
+- **new \u2192 Planned Capability Definition.** Define the capabilities the product *should* have. Use
+  \`[planned]\` items; evidence is not required yet.
+- **pre-ai \u2192 Existing Capability Discovery.** Document the capabilities the system *already has*, as a
+  structured inventory with **evidence**, status and gaps \u2014 a photograph of what exists today, not a
+  wishlist.
+- **legacy \u2192 Legacy Capability Discovery.** Same inventory plus **criticality**, **change risk**,
+  **operational dependency** and **modernization notes** per capability.
+
+## Capability status values
+
+Classify every discovered capability with exactly one status:
+
+- \`implemented\` \u2014 clearly present; **must have evidence**.
+- \`partial\` \u2014 exists but incomplete.
+- \`inferred\` \u2014 likely present from indirect signals; not yet confirmed.
+- \`risky\` \u2014 exists but carries technical/operational risk.
+- \`deprecated\` \u2014 present but obsolete / being replaced.
+- \`unknown\` \u2014 not enough evidence to classify.
+
+Never mark a capability \`implemented\` without evidence. When evidence is indirect, use \`inferred\`.
+When there is no evidence at all, use \`unknown\` and write \`Evidence: - pending validation\`.
+
 ## Input Required
 
 Provide \`.kaddo/context-pack.md\` as the primary input.
@@ -2230,14 +2256,20 @@ Analyze the context pack and identify:
 7. Suggested ownership.
 8. Candidate code globs if evident.
 
+For **pre-ai** and **legacy**, produce the richer inventory (see Output Format): a
+\`## Capability Inventory\` with status + evidence per capability, a \`## Capability Gaps\` section, and
+\`## Roadmap Candidate Signals\` (signals only \u2014 never a formal roadmap). For **legacy**, add
+\`Criticality\`, \`Change risk\`, \`Operational dependency\` and \`Modernization notes\` per capability.
+
 ## Constraints
 
 - Do not invent business context.
-- Mark assumptions clearly.
+- Do not invent evidence; never mark \`implemented\` without a concrete path/route/table/function.
+- Mark assumptions clearly; use \`inferred\`/\`unknown\` when evidence is missing.
 - Prefer "candidate capability" when evidence is incomplete.
 - Do not produce implementation tasks.
-- Do not generate a roadmap yet.
-- Do not create ADRs.
+- Do not generate a roadmap yet \u2014 only \`[gap]\` and \`[candidate]\` signals.
+- Do not create ADRs or Work Items.
 - Do not write code.
 
 ## Output Format
@@ -2280,6 +2312,47 @@ Generated from Kaddo Context Pack.
 ## Suggested Next Step
 \`\`\`
 
+### Output Format \u2014 pre-ai / legacy (Existing Capability Discovery)
+
+\`\`\`markdown
+# Existing Capabilities
+
+## Capability Inventory
+
+### <Capability name>
+
+- Status: implemented | partial | inferred | risky | deprecated | unknown
+- Capability type: business | product | technical | integration | operational
+- User-facing: yes | no | internal
+- Evidence:
+  - \`<path/to/file>\`
+  - \`<route>\` / \`<table>\` / \`<function>\`
+- Related flows / data / integrations:
+- Current behavior:
+- Known constraints:
+- Risks or uncertainty:
+- Open questions:
+  - [open] ...
+<!-- legacy only: -->
+- Criticality: low | medium | high
+- Change risk: low | medium | high
+- Operational dependency:
+- Modernization notes:
+
+## Capability Gaps
+
+- [gap] <Gap description>
+  - Related capability: <name>
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
+
+## Roadmap Candidate Signals
+
+- [candidate] <Potential roadmap candidate>
+  - Based on: partial capability | gap | risk | open question | business goal
+  - Related capability: <name>
+\`\`\`
+
 ## Where to Save the Result
 
 Save the output as \`knowledge/product/capabilities.md\`.
@@ -2396,12 +2469,24 @@ Use this agent after capabilities and architecture are understood (or at least a
 
 ## Input Required
 
-Provide \`.kaddo/context-pack.md\` as the primary input.
+Provide \`.kaddo/context-pack.md\` as the primary input, and treat
+\`knowledge/product/capabilities.md\` as the **primary source for roadmap candidates** (VS-074).
+
+Derive roadmap candidates from the capability inventory, prioritizing:
+
+- \`partial\` capabilities (finish what exists)
+- \`## Capability Gaps\` (\`[gap]\` items, especially Impact: high)
+- \`## Roadmap Candidate Signals\` (\`[candidate]\` items)
+- \`risky\` capabilities (especially in legacy \u2014 stabilize before extending)
+- resolved/assumed/deferred open questions and business goals
+- technical risks and decision candidates
+
+**Do not** build a roadmap from general ideas when \`capabilities.md\` is still a placeholder or weak:
+if capabilities are not yet discovered, recommend running the \`capability-agent\` first.
 
 Optionally provide (use whatever is available; mark anything missing as an assumption or
 open question):
 
-- \`knowledge/product/capabilities.md\`
 - \`knowledge/tech/current-state.md\`
 - \`knowledge/legacy/risks.md\`
 - \`knowledge/legacy/unknowns.md\`
@@ -2809,6 +2894,10 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 **Open questions:**
 
 **Suggested ownership (code globs):**
+
+**Related capability:** <!-- recommended (VS-074): the capability from
+knowledge/product/capabilities.md this Work Item advances, so work traces back to a real capability.
+Add \`related_capability: <name>\` to the front matter when known. -->
 \`\`\`
 
 ## Where to Save the Result
@@ -6992,6 +7081,9 @@ function isPlaceholderLine(line) {
   if (/^[-*]\s+(\[[^\]]+\]\s*)?_.+_$/.test(t)) return true;
   if (/^[-*]\s+\[[^\]]+\]\s*$/.test(t)) return true;
   if (/^_(?:Describe|List|Document|What|Which|Who|Use|To be defined|No production code)\b/i.test(t)) return true;
+  if (/<[^>]+>/.test(t)) return true;
+  if (/^[-*]\s+[^:]+:\s*$/.test(t)) return true;
+  if (/^[-*]\s+[^:]+:\s*\S.*\s\|\s/.test(t)) return true;
   return false;
 }
 function isStructuralLine(line, inFrontMatter) {
@@ -7205,10 +7297,10 @@ function extractFromMarkdown(md) {
     }
     const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/);
     if (m) {
-      const raw = m[1].trim();
-      if (!raw || /^_.*_$/.test(raw)) continue;
-      const { text: text3, resolution_status } = parseResolution(raw);
-      if (text3) out.push({ text: text3, resolution_status });
+      const bullet = m[1].trim();
+      if (!bullet || /^_.*_$/.test(bullet)) continue;
+      const { text: text3, resolution_status } = parseResolution(bullet);
+      if (text3) out.push({ text: text3, resolution_status, line: i + 1, raw: line.trim() });
     }
   }
   return out;
@@ -7248,12 +7340,15 @@ function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
       questions.push({
         id: `OQ-${String(seq).padStart(3, "0")}`,
         source,
+        sourcePath: source,
+        line: eq.line,
+        raw: eq.raw,
         section: "Open Questions",
         question: eq.text,
         classification,
         resolution_status: eq.resolution_status,
         reason,
-        ...eq.resolution_note ? { resolution_note: eq.resolution_note } : {},
+        ...eq.resolution_note ? { resolution_note: eq.resolution_note, note: eq.resolution_note } : {},
         ...classification === "blocking" && eq.resolution_status === "open" ? { suggested_assumption: suggestedAssumption(eq.text) } : {}
       });
     }
@@ -7323,17 +7418,23 @@ function renderOpenQuestionsMarkdown(r) {
   L.push("## Blocking Open Questions", "");
   if (blockingOpen.length === 0) L.push("_None \u2014 nothing blocks readiness._", "");
   for (const q of blockingOpen) {
-    L.push(`### ${q.id}`, "");
-    L.push(`- Source: \`${q.source}\``);
-    L.push(`- Question: ${q.question}`);
+    L.push(`### ${q.question}`, "");
+    L.push(`- Status: ${q.resolution_status}`);
+    L.push(`- Severity: ${q.classification}`);
+    L.push(`- Source: \`${q.sourcePath}:${q.line}\``);
     L.push(`- Reason: ${q.reason}`);
-    if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
+    L.push("");
+    L.push("Suggested action:", "");
+    L.push("```md");
+    L.push(`- [assumed] ${q.question}`);
+    L.push(`  - note: ${q.suggested_assumption ?? "<editable assumption for the MVP>"}`);
+    L.push("```");
     L.push("");
   }
   const renderStatusList = (title, items) => {
     L.push(`## ${title}`, "");
     if (items.length === 0) L.push("_None._");
-    for (const q of items) L.push(`- ${q.question}${q.resolution_note ? ` \u2014 _${q.resolution_note}_` : ""}`);
+    for (const q of items) L.push(`- ${q.question} \u2014 \`${q.sourcePath}:${q.line}\`${q.note ? ` \u2014 _${q.note}_` : ""}`);
     L.push("");
   };
   renderStatusList("Resolved", r.resolved_questions);
@@ -7808,10 +7909,11 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (!exists(join(dir, ".kaddo", "understand.md"))) {
     return { id: "understand", phase: "Discovery", label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand", reason: "No understand handoff has been generated yet." };
   }
-  const refine = (id, agent, target, quality) => ({
+  const discovery = state === "pre-ai" || state === "legacy";
+  const refine = (id, agent, target, quality, verb = "complete") => ({
     id,
     phase: "Knowledge Refinement",
-    label: `Use ${agent} to complete \`${target}\`.`,
+    label: `Use ${agent} to ${verb} \`${target}\`.`,
     agent,
     target,
     reason: `${target} is ${quality === "missing" ? "missing" : "still a bootstrap placeholder or too thin"}.`,
@@ -7823,8 +7925,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   });
   if (qBusiness !== "useful") return refine("refine-business", "business-agent", B, qBusiness);
   if (qProduct !== "useful" || qCap !== "useful") {
-    const target = qCap !== "useful" ? CAP : P;
-    return refine("refine-product", "capability-agent", target, qCap !== "useful" ? qCap : qProduct);
+    if (qCap !== "useful") {
+      return refine("refine-product", "capability-agent", CAP, qCap, discovery ? "discover and document existing system capabilities in" : "complete");
+    }
+    return refine("refine-product", "capability-agent", P, qProduct);
   }
   if (qCurrentState !== "useful") return refine("refine-current-state", "architecture-agent", CS, qCurrentState);
   if (qCodebase !== "useful") {
@@ -7833,7 +7937,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   }
   const oq = buildOpenQuestionsReport(dir, now);
   if (oq.summary.blocking_open > 0) {
-    return { id: "questions", phase: "Knowledge Refinement", label: "Resolve, assume or defer the blocking open questions (`kaddo questions`).", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
+    return { id: "questions", phase: "Knowledge Refinement", label: "Run `kaddo questions` to see source locations and resolution guidance, then resolve, assume or defer the blocking open questions.", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
   }
   const roadmap = roadmapSignal(dir);
   if (roadmap !== "has-candidates") {
@@ -12148,39 +12252,77 @@ _Document the product capabilities that should exist._
 `,
     "pre-ai": `# Existing Capabilities
 
-## Observed capabilities
+> Discover the capabilities the system already has (evidence-backed). Use the capability-agent to fill this in \u2014 run \`kaddo add agents\`, then feed it the context pack.
 
-- [observed] _Capability observed in the existing system._
+## Capability Inventory
 
-## Partial capabilities
+### <Capability name>
 
-- [partial] _Capability that appears incomplete or uncertain._
+- Status: implemented | partial | inferred | risky | deprecated | unknown
+- Capability type: business | product | technical | integration | operational
+- User-facing: yes | no | internal
+- Evidence:
+  - _\`path/to/file\`, route, table or function \u2014 or \`pending validation\`._
+- Related flows / data / integrations:
+  - _..._
+- Current behavior:
+  - _..._
+- Known constraints:
+  - _..._
+- Risks or uncertainty:
+  - _..._
+- Open questions:
+  - [open] _..._
 
-## Assumptions
+## Capability Gaps
 
-- [assumed] _Safe assumption to confirm later._
+- [gap] _Gap description._
+  - Related capability: _<name>_
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
 
-## Open questions
+## Roadmap Candidate Signals
 
-- [open] _What capability is unclear?_
+- [candidate] _Potential roadmap candidate._
+  - Based on: partial capability | gap | risk | open question | business goal
+  - Related capability: _<name>_
 `,
     legacy: `# Legacy Capabilities
 
-## Critical capabilities
+> Discover existing capabilities plus their criticality, change risk and modernization signals. Use the capability-agent to fill this in.
 
-- [critical] _Capability that must keep working._
+## Capability Inventory
 
-## Risky capabilities
+### <Capability name>
 
-- [risky] _Capability that is hard to change or poorly understood._
+- Status: implemented | partial | inferred | risky | deprecated | unknown
+- Capability type: business | product | technical | integration | operational
+- User-facing: yes | no | internal
+- Criticality: low | medium | high
+- Change risk: low | medium | high
+- Operational dependency:
+  - _..._
+- Evidence:
+  - _\`path/to/file\`, route, table or function \u2014 or \`pending validation\`._
+- Current behavior:
+  - _..._
+- Modernization notes:
+  - _..._
+- Open questions:
+  - [open] _..._
 
-## Replacement candidates
+## Capability Gaps
 
-- [candidate] _Capability that may be modernized later._
+- [gap] _Gap description._
+  - Related capability: _<name>_
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
 
-## Open questions
+## Roadmap Candidate Signals
 
-- [open] _What capability risk is unclear?_
+- [candidate] _Potential modernization or roadmap candidate._
+  - Based on: partial capability | gap | risk | open question | business goal
+  - Related capability: _<name>_
 `
   },
   codebase: {
@@ -13443,7 +13585,8 @@ function runDrift(opts = {}) {
 // src/commands/questions.ts
 function runQuestions(opts = {}) {
   const dir = cwd();
-  requireConfig(dir);
+  const config = requireConfig(dir);
+  const es = projectLanguage(config) === "es";
   const report = buildOpenQuestionsReport(dir);
   if (opts.output) {
     intro2("kaddo questions");
@@ -13462,22 +13605,67 @@ function runQuestions(opts = {}) {
   console.log(`Open questions detected: ${s.open_questions}`);
   console.log(`By resolution \u2014 open: ${s.resolution.open}, resolved: ${s.resolution.resolved}, assumed: ${s.resolution.assumed}, deferred: ${s.resolution.deferred}`);
   console.log(`Roadmap readiness: ${s.roadmap_readiness === "needs_decisions" ? "needs decisions" : s.roadmap_readiness} (blocking open: ${s.blocking_open}, important open: ${s.important_open})`);
-  const list2 = (title, qs) => {
+  const list2 = (title, qs, opts2 = {}) => {
     if (qs.length === 0) return;
     console.log("");
     console.log(`${title}:`);
-    for (const q of qs.slice(0, 8)) console.log(`- ${q.question}${q.resolution_note ? ` \u2014 ${q.resolution_note}` : ""}`);
-    if (qs.length > 8) console.log(`  \u2026and ${qs.length - 8} more`);
+    console.log("");
+    qs.slice(0, 12).forEach((q, i) => {
+      console.log(`${i + 1}. ${q.question}`);
+      console.log(`   Source: ${q.sourcePath}:${q.line}`);
+      console.log(`   Status: ${q.resolution_status}`);
+      console.log(`   Severity: ${q.classification}`);
+      if (q.note) console.log(`   Note: ${q.note}`);
+      if (opts2.example && q.resolution_status === "open") {
+        console.log("   Suggested action:");
+        console.log(`     ${es ? "Cambia [open] por [resolved], [assumed] o [deferred]." : "Change [open] to [resolved], [assumed] or [deferred]."}`);
+        console.log("   Example:");
+        console.log(`     - [assumed] ${q.question}`);
+        console.log(`       - note: ${es ? "<supuesto editable para el MVP>" : "<editable assumption for the MVP>"}`);
+      }
+      console.log("");
+    });
+    if (qs.length > 12) console.log(`  \u2026and ${qs.length - 12} more`);
   };
-  list2("Blocking (open)", report.blocking_questions.filter((q) => q.resolution_status === "open"));
+  list2("Blocking (open)", report.blocking_questions.filter((q) => q.resolution_status === "open"), { example: true });
+  list2("Important (open)", report.important_questions.filter((q) => q.resolution_status === "open"));
   list2("Resolved", report.resolved_questions);
   list2("Assumed", report.assumed_questions);
   list2("Deferred", report.deferred_status_questions);
+  printResolutionGuide(es);
   console.log("");
   console.log("Suggested next:");
   console.log(report.recommended_next_step);
   printCommandFooter("questions");
 }
+function printResolutionGuide(es) {
+  console.log("");
+  if (es) {
+    console.log("C\xF3mo resolver");
+    console.log("");
+    console.log("Edita el archivo indicado en Source y cambia el marcador:");
+    console.log("  [open]     \u2192 sigue abierta");
+    console.log("  [resolved] \u2192 respuesta confirmada");
+    console.log("  [assumed]  \u2192 supuesto seguro por ahora");
+    console.log("  [deferred] \u2192 decisi\xF3n aplazada");
+    console.log("");
+    console.log("Agrega una nota debajo de la pregunta cuando sea posible:");
+    console.log("  - [assumed] \xBFPregunta?");
+    console.log("    - note: Se asume X para el MVP porque Y.");
+  } else {
+    console.log("How to resolve");
+    console.log("");
+    console.log("Edit the file shown in Source and change the marker:");
+    console.log("  [open]     \u2192 still unresolved");
+    console.log("  [resolved] \u2192 confirmed answer");
+    console.log("  [assumed]  \u2192 safe assumption for now");
+    console.log("  [deferred] \u2192 intentionally postponed");
+    console.log("");
+    console.log("Add a note below the question when possible:");
+    console.log("  - [assumed] Question?");
+    console.log("    - note: Assume X for the MVP because Y.");
+  }
+}
 
 // src/commands/adapters.ts
 var ADAPTER_LIST = ADAPTERS.map((a) => a.id).join(", ");

package/package.json

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