@kaddo/cli 3.38.0 → 3.39.0

package/README.md

@@ -535,6 +535,7 @@ create --from roadmap → owners → guard → explain`.
 | 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) {
@@ -7817,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"}.`,
@@ -7832,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") {
@@ -12157,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: {

package/package.json

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