@kaddo/cli 3.38.0 → 3.39.1

package/README.md

@@ -535,6 +535,8 @@ 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 |
+| v3.39.1 | Domain-oriented capability inventory: pre-ai/legacy `capabilities.md` groups capabilities under `## Capability Domains` (functional domains, not technical folders); gaps/candidates name their `Domain`; roadmap-agent reads it as a domain map; work-item-agent recommends `related_domain` + `related_capability` |
 
 **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 (Domain-Oriented Capability Inventory).** Document the
+  capabilities the system *already has*, **grouped by functional domain**, with **evidence**, status
+  and gaps \u2014 a photograph of what exists today, not a wishlist.
+- **legacy \u2192 Legacy Capability Discovery.** Same domain-oriented inventory plus **criticality**,
+  **change risk**, **operational dependency** and **modernization notes** per domain/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,22 @@ Analyze the context pack and identify:
 7. Suggested ownership.
 8. Candidate code globs if evident.
 
+For **pre-ai** and **legacy**, produce the domain-oriented inventory (see Output Format): a
+\`## Capability Domains\` section where each \`### Domain:\` groups capabilities by functional
+responsibility (with Purpose + Evidence summary), each \`#### Capability:\` has status + evidence, plus
+\`## Capability Gaps\` and \`## Roadmap Candidate Signals\` (signals only \u2014 never a formal roadmap). Every
+gap and candidate names its \`Domain\` and \`Related capability\`. For **legacy**, add \`Criticality\`,
+\`Change risk\`, \`Operational dependency\` and \`Modernization notes\`.
+
 ## 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 +2314,71 @@ Generated from Kaddo Context Pack.
 ## Suggested Next Step
 \`\`\`
 
+### Output Format \u2014 pre-ai / legacy (Domain-Oriented Capability Inventory)
+
+Group capabilities by **functional domain**, not by technical folder. Infer domains from the system
+(e.g. Loyalty, Billing & Subscriptions, Communications, Operations & Automation) \u2014 do not use a rigid
+universal taxonomy and do not use folders like \`src/components\` or \`src/app/api\` as domains. A single
+capability may have evidence across layers (frontend hook + API route + table + webhook).
+
+\`\`\`markdown
+# Existing Capabilities
+
+## Capability Domains
+
+### Domain: <Domain name>
+
+**Purpose:** <functional responsibility of this domain>
+
+**Evidence summary:**
+- \`<path>\` / \`<route>\` / \`<table>\` / \`<function>\`
+<!-- legacy only: -->
+**Criticality:** low | medium | high
+**Change risk:** low | medium | high
+**Operational dependency:** <...>
+
+#### Capability: <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:
+- Related data:
+- Related integrations:
+- Current behavior:
+- Known constraints:
+- Risks or uncertainty:
+- Open questions:
+  - [open] ...
+<!-- legacy only, per capability: Modernization notes -->
+
+## Capability Gaps
+
+- [gap] <Gap description>
+  - Domain: <Domain name>
+  - Related capability: <name>
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
+
+## Roadmap Candidate Signals
+
+- [candidate] <Potential roadmap candidate>
+  - Domain: <Domain name>
+  - Related capability: <name>
+  - Based on: partial capability | gap | risk | open question | business goal
+\`\`\`
+
+### Domain grouping rules
+
+- Group by **functional responsibility**, never by technical folder.
+- A capability may span multiple layers \u2014 list all its evidence.
+- Keep the VS-074 evidence rule: \`implemented\` needs concrete evidence; indirect \u2192 \`inferred\`; none \u2192
+  \`unknown\`. Never invent domains, paths, routes, tables or functions.
+- Every \`[gap]\` names its \`Domain\` and \`Related capability\`; every \`[candidate]\` names \`Domain\`,
+  \`Related capability\` and \`Based on\`.
+
 ## Where to Save the Result
 
 Save the output as \`knowledge/product/capabilities.md\`.
@@ -2396,12 +2495,34 @@ 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).
+
+Read \`capabilities.md\` as a **map of functional domains** (\`## Capability Domains\`). Derive roadmap
+candidates from the 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
+
+Each roadmap candidate should reference its \`Domain\` and \`Related capability\`, e.g.:
+
+\`\`\`md
+- [candidate] Harden idempotent payment webhook processing.
+  - Domain: Billing & Subscriptions
+  - Related capability: Payment Webhook Processing
+  - Based on: risk
+\`\`\`
+
+**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 +2930,11 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 **Open questions:**
 
 **Suggested ownership (code globs):**
+
+**Related domain / capability:** <!-- recommended (VS-074/074.1): the functional domain and the
+capability from knowledge/product/capabilities.md this Work Item advances, so work traces back to the
+system's functional map. Add \`related_domain: <domain>\` and \`related_capability: <name>\` to the front
+matter when known. -->
 \`\`\`
 
 ## Where to Save the Result
@@ -6992,6 +7118,12 @@ 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;
+  if (/^\*\*[^*]+:\*\*\s*$/.test(t)) return true;
+  if (/^\*\*[^*]+:\*\*\s*_.*_$/.test(t)) return true;
+  if (/^\*\*[^*]+:\*\*\s*\S.*\s\|\s/.test(t)) return true;
   return false;
 }
 function isStructuralLine(line, inFrontMatter) {
@@ -7817,10 +7949,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 +7965,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 grouped by functional domains 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 +12292,99 @@ _Document the product capabilities that should exist._
 `,
     "pre-ai": `# Existing Capabilities
 
-## Observed capabilities
-
-- [observed] _Capability observed in the existing system._
+> Discover the capabilities the system already has, grouped by **functional domain** (not technical folders), evidence-backed. Use the capability-agent to fill this in \u2014 run \`kaddo add agents\`, then feed it the context pack.
+
+## Capability Domains
+
+### Domain: <Domain name>
+
+**Purpose:** _What functional responsibility this domain covers._
+
+**Evidence summary:**
+- _\`path\`, route, table or function._
+
+#### Capability: <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 or function \u2014 or \`pending validation\`._
+- Related flows:
+  - _..._
+- Related data:
+  - _..._
+- Related integrations:
+  - _..._
+- Current behavior:
+  - _..._
+- Known constraints:
+  - _..._
+- Risks or uncertainty:
+  - _..._
+- Open questions:
+  - [open] _..._
+
+## Capability Gaps
+
+- [gap] _Gap description._
+  - Domain: _<Domain name>_
+  - Related capability: _<name>_
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
+
+## Roadmap Candidate Signals
+
+- [candidate] _Potential roadmap candidate._
+  - Domain: _<Domain name>_
+  - Related capability: _<name>_
+  - Based on: partial capability | gap | risk | open question | business goal
+`,
+    legacy: `# Legacy Capabilities
 
-## Partial capabilities
+> Discover existing capabilities grouped by **functional domain** (not technical folders), plus criticality, change risk and modernization signals. Use the capability-agent to fill this in.
 
-- [partial] _Capability that appears incomplete or uncertain._
+## Capability Domains
 
-## Assumptions
+### Domain: <Domain name>
 
-- [assumed] _Safe assumption to confirm later._
+**Purpose:** _What functional responsibility this domain covers._
 
-## Open questions
+**Criticality:** low | medium | high
+**Change risk:** low | medium | high
+**Operational dependency:** _..._
 
-- [open] _What capability is unclear?_
-`,
-    legacy: `# Legacy Capabilities
-
-## Critical capabilities
+**Evidence summary:**
+- _\`path\`, route, table or function._
 
-- [critical] _Capability that must keep working._
+#### Capability: <Capability name>
 
-## Risky capabilities
+- 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\`._
+- Current behavior:
+  - _..._
+- Modernization notes:
+  - _..._
+- Open questions:
+  - [open] _..._
 
-- [risky] _Capability that is hard to change or poorly understood._
+## Capability Gaps
 
-## Replacement candidates
+- [gap] _Gap description._
+  - Domain: _<Domain name>_
+  - Related capability: _<name>_
+  - Impact: low | medium | high
+  - Possible roadmap candidate: yes | no
 
-- [candidate] _Capability that may be modernized later._
-
-## Open questions
+## Roadmap Candidate Signals
 
-- [open] _What capability risk is unclear?_
+- [candidate] _Potential modernization or roadmap candidate._
+  - Domain: _<Domain name>_
+  - Related capability: _<name>_
+  - Based on: partial capability | gap | risk | open question | business goal
 `
   },
   codebase: {

package/package.json

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