@kaddo/cli 3.39.0 → 3.40.0

package/README.md

@@ -536,6 +536,8 @@ create --from roadmap → owners → guard → explain`.
 | 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` |
+| v3.40 | ADR materialization: `kaddo adr` (alias `decisions`) detects decision candidates + ADRs and hands off the ADR files to create; `tech_decisions` status (none/candidates/draft-adrs/accepted-adrs) surfaced in `explain`/`context`/`understand`; adr-writing skill formalized |
 
 **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"
+  },
+  adr: {
+    question: "Which technical decisions still need to become ADRs?",
+    next: "Use the adr-writing skill to draft ADRs, then mark them accepted when confirmed"
   }
 };
 function commandFooterLines(name) {
@@ -1546,37 +1550,56 @@ The context pack, the relevant Work Item or architecture note, and the decision
 
 ## Output
 
-A single ADR containing: context, the decision, alternatives considered, consequences, the code
-paths it governs (\`code:\` globs when known) and the decision status (proposed / accepted /
-superseded).
+A single ADR (saved under \`knowledge/tech/decisions/\`) with front matter and the standard sections:
+context, options considered, the decision, consequences, related capabilities and related Work Items.
+Status is one of \`draft\`, \`accepted\`, \`superseded\`, \`deprecated\`.
+
+## Materializing from decision candidates (VS-075)
+
+When \`knowledge/tech/decisions/\` is empty but \`knowledge/tech/decision-candidates.md\` holds
+candidates, materialize each candidate as an ADR **draft** \u2014 copy its context and options, leave the
+decision and consequences as \`[open]\` for human confirmation, and record its origin with
+\`created_from: knowledge/tech/decision-candidates.md\`. Never mark a materialized draft \`accepted\`;
+acceptance is a human decision.
 
 ## Rules
 
 - One ADR = one decision. Never mix unrelated decisions.
 - Never invent decisions; never write an ADR without a clear reason.
-- Record alternatives honestly, including the one chosen and why.
+- Record alternatives honestly, including the one chosen and why (or \`[open]\` when undecided).
 - Prefer narrow governed \`code:\` globs over broad ones.
 
 ## Quality checklist
 
 - Context explains why the decision was needed.
-- The decision and its alternatives are explicit.
+- The decision and its alternatives are explicit (or explicitly \`[open]\`).
 - Consequences (positive and negative) are stated.
 - Status and governed paths are present.
 
 ## Example output
 
 \`\`\`md
-# ADR-0007 \u2014 Use SQLite for local persistence
-Status: accepted
+---
+type: adr
+status: draft | accepted | superseded | deprecated
+date: YYYY-MM-DD
+created_from: knowledge/tech/decision-candidates.md
+---
+
+# ADR-001 \u2014 Use INTERNAL_CRON_SECRET for internal endpoint protection
+
 ## Context
 ...
-## Decision
-...
-## Alternatives considered
+## Options Considered
 ...
+## Decision
+[open]
 ## Consequences
-...
+[open]
+## Related Capabilities
+- <domain / capability>
+## Related Work Items
+- <WI id>
 \`\`\`
 `
 );
@@ -2213,11 +2236,11 @@ 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.
+- **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
 
@@ -2256,10 +2279,12 @@ 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.
+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
 
@@ -2312,36 +2337,50 @@ Generated from Kaddo Context Pack.
 ## Suggested Next Step
 \`\`\`
 
-### Output Format \u2014 pre-ai / legacy (Existing Capability Discovery)
+### 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 Inventory
+## Capability Domains
 
-### <Capability name>
+### 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 / data / integrations:
+  - \`<path/to/file>\` / \`<route>\` / \`<table>\` / \`<function>\`
+- Related flows:
+- Related data:
+- Related 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:
+<!-- 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
@@ -2349,10 +2388,20 @@ Generated from Kaddo Context Pack.
 ## Roadmap Candidate Signals
 
 - [candidate] <Potential roadmap candidate>
-  - Based on: partial capability | gap | risk | open question | business goal
+  - 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\`.
@@ -2472,7 +2521,8 @@ Use this agent after capabilities and architecture are understood (or at least a
 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:
+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)
@@ -2481,6 +2531,15 @@ Derive roadmap candidates from the capability inventory, prioritizing:
 - 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.
 
@@ -2895,9 +2954,17 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 
 **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. -->
+**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. -->
+
+**Related decisions:** <!-- recommended (VS-075): if this Work Item is affected by a technical
+decision, reference the ADR under knowledge/tech/decisions/ as \`related_decisions: [ADR-001-...]\`. If
+the decision is still a candidate in knowledge/tech/decision-candidates.md with no ADR yet, **warn**
+that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and record
+\`decision_candidates: [<title>]\` \u2014 do not implement work that depends on an unformalized decision
+without surfacing it. -->
 \`\`\`
 
 ## Where to Save the Result
@@ -3474,6 +3541,12 @@ architecture, persistence, authentication or the Work Item's scope. Block only o
 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.
 
+Also check **technical decisions** (VS-075): if the Work Item touches a decision that is still a
+candidate in \`knowledge/tech/decision-candidates.md\` with no ADR under \`knowledge/tech/decisions/\`
+(run \`kaddo adr\`), **warn** and recommend materializing it as an ADR (adr-writing skill) before
+implementing \u2014 do not silently implement work that depends on an unformalized architectural,
+security, data, integration or infrastructure decision.
+
 ## When to Use
 
 Use this agent after the work-item-agent has produced a clear, traceable Work Item under
@@ -7084,6 +7157,9 @@ function isPlaceholderLine(line) {
   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) {
@@ -7926,7 +8002,7 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (qBusiness !== "useful") return refine("refine-business", "business-agent", B, qBusiness);
   if (qProduct !== "useful" || qCap !== "useful") {
     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", CAP, qCap, discovery ? "discover and document existing system capabilities grouped by functional domains in" : "complete");
     }
     return refine("refine-product", "capability-agent", P, qProduct);
   }
@@ -8046,6 +8122,76 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   };
 }
 
+// src/core/decisions.ts
+var CANDIDATES_PATH = "knowledge/tech/decision-candidates.md";
+var DECISIONS_DIR = "knowledge/tech/decisions";
+function slugify2(s) {
+  return s.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function parseDecisionCandidates(md) {
+  const out = [];
+  for (const line of md.split(/\r?\n/)) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      const t = m[1].trim();
+      if (t && !/^_.*_$/.test(t)) out.push(t);
+    }
+  }
+  return out;
+}
+function countAdrs(dir) {
+  const base = join(dir, DECISIONS_DIR);
+  if (!exists(base)) return { total: 0, draft: 0, accepted: 0 };
+  let total = 0;
+  let draft = 0;
+  let accepted = 0;
+  for (const entry of readDir(base)) {
+    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
+    const full = join(base, entry);
+    if (!isFile(full)) continue;
+    total += 1;
+    let content = "";
+    try {
+      content = readFile(full);
+    } catch {
+      continue;
+    }
+    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
+    if (status === "accepted") accepted += 1;
+    else draft += 1;
+  }
+  return { total, draft, accepted };
+}
+function buildTechDecisions(dir) {
+  const candFile = join(dir, CANDIDATES_PATH);
+  let titles = [];
+  if (exists(candFile)) {
+    try {
+      titles = parseDecisionCandidates(readFile(candFile));
+    } catch {
+      titles = [];
+    }
+  }
+  const { total, draft, accepted } = countAdrs(dir);
+  const candidate_list = titles.map((title, i) => {
+    const n = String(total + i + 1).padStart(3, "0");
+    return { title, source: CANDIDATES_PATH, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
+  });
+  let status;
+  if (accepted > 0) status = "accepted-adrs";
+  else if (total > 0) status = "draft-adrs";
+  else if (titles.length > 0) status = "candidates";
+  else status = "none";
+  return {
+    status,
+    candidates: titles.length,
+    adrs: total,
+    draft_adrs: draft,
+    accepted_adrs: accepted,
+    candidate_list
+  };
+}
+
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
 function normalizeTitle(t) {
@@ -8257,7 +8403,8 @@ function buildProjectExplanation(dir) {
     missingKnowledge,
     suggestedNextSteps,
     readiness,
-    nextStepRecommendation: readiness.nextStepRecommendation
+    nextStepRecommendation: readiness.nextStepRecommendation,
+    techDecisions: buildTechDecisions(dir)
   };
 }
 function stateLabel(state) {
@@ -8471,6 +8618,16 @@ function renderExplanationHuman(exp) {
   lines.push("### Recommended next step");
   lines.push(r.recommended_next_step.label);
   lines.push("");
+  const td = exp.techDecisions;
+  lines.push("## Tech Decisions");
+  lines.push(`- Decision candidates: ${td.candidates}`);
+  lines.push(`- ADRs: ${td.adrs} (draft: ${td.draft_adrs}, accepted: ${td.accepted_adrs})`);
+  lines.push(`- Status: ${td.status}`);
+  if (td.candidates > 0 && td.adrs === 0) {
+    lines.push("");
+    lines.push("Use the adr-writing skill to materialize decision candidates into ADRs (`kaddo adr`) before implementing related technical Work Items.");
+  }
+  lines.push("");
   return lines.join("\n").trimEnd() + "\n";
 }
 function renderExplanationAgent(exp) {
@@ -8815,6 +8972,10 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     }
   });
   const nextStepRecommendation = resolveNextStep(dir, now);
+  const techDecisions = buildTechDecisions(dir);
+  if (techDecisions.candidates > 0 && techDecisions.adrs === 0) {
+    missing.push(`${techDecisions.candidates} technical decision candidate(s) not yet materialized as ADRs (run \`kaddo adr\`).`);
+  }
   const unifiedPhase = {
     ...phase,
     nextStep: nextStepRecommendation.label,
@@ -8852,6 +9013,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase: unifiedPhase,
     nextStepRecommendation,
+    techDecisions,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -9275,12 +9437,12 @@ function renderUnderstandTerminal(plan) {
 
 // src/core/delivery.ts
 import { parse as parseYaml10 } from "yaml";
-function slugify2(s) {
+function slugify3(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function toActive(a) {
   const id = a.id || a.title || "WI";
-  return { id, title: a.title || id, type: a.type, slug: slugify2(a.title || id) };
+  return { id, title: a.title || id, type: a.type, slug: slugify3(a.title || id) };
 }
 function activeWorkItems(dir) {
   return discoverWorkItems(dir).filter((a) => a.lifecycle === "in-progress").map(toActive);
@@ -9386,6 +9548,13 @@ function runUnderstand() {
       for (const s of recSkills) console.log(`  - ${s}`);
     }
   }
+  const td = exp.techDecisions;
+  if (td.candidates > 0 && td.adrs === 0) {
+    console.log("");
+    console.log(`Tech decisions: ${td.candidates} decision candidate(s) not yet materialized as ADRs.`);
+    console.log("  \u2192 Use the adr-writing skill to create ADR drafts from `knowledge/tech/decision-candidates.md`");
+    console.log("    into `knowledge/tech/decisions/` before implementing affected technical Work Items (`kaddo adr`).");
+  }
   if (exp.externalCapsules.length > 0) {
     console.log("");
     console.log("External knowledge:");
@@ -11900,7 +12069,7 @@ var MODULE_TYPES = [
   "data",
   "unknown"
 ];
-function slugify3(name) {
+function slugify4(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
@@ -11920,7 +12089,7 @@ function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
 }
 function buildModule(input) {
-  const id = slugify3(input.name);
+  const id = slugify4(input.name);
   const base = moduleDir(id);
   return {
     id,
@@ -12252,18 +12421,29 @@ _Document the product capabilities that should exist._
 `,
     "pre-ai": `# Existing 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.
+> 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._
 
-## Capability Inventory
+**Evidence summary:**
+- _\`path\`, route, table or function._
 
-### <Capability name>
+#### 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 / data / integrations:
+- Related flows:
+  - _..._
+- Related data:
+  - _..._
+- Related integrations:
   - _..._
 - Current behavior:
   - _..._
@@ -12277,6 +12457,7 @@ _Document the product capabilities that should exist._
 ## Capability Gaps
 
 - [gap] _Gap description._
+  - Domain: _<Domain name>_
   - Related capability: _<name>_
   - Impact: low | medium | high
   - Possible roadmap candidate: yes | no
@@ -12284,24 +12465,32 @@ _Document the product capabilities that should exist._
 ## Roadmap Candidate Signals
 
 - [candidate] _Potential roadmap candidate._
-  - Based on: partial capability | gap | risk | open question | business goal
+  - Domain: _<Domain name>_
   - Related capability: _<name>_
+  - Based on: partial capability | gap | risk | open question | business goal
 `,
     legacy: `# Legacy Capabilities
 
-> Discover existing capabilities plus their criticality, change risk and modernization signals. Use the capability-agent to fill this in.
+> 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.
+
+## Capability Domains
 
-## Capability Inventory
+### Domain: <Domain name>
 
-### <Capability name>
+**Purpose:** _What functional responsibility this domain covers._
+
+**Criticality:** low | medium | high
+**Change risk:** low | medium | high
+**Operational dependency:** _..._
+
+**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
-- 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:
@@ -12314,6 +12503,7 @@ _Document the product capabilities that should exist._
 ## Capability Gaps
 
 - [gap] _Gap description._
+  - Domain: _<Domain name>_
   - Related capability: _<name>_
   - Impact: low | medium | high
   - Possible roadmap candidate: yes | no
@@ -12321,8 +12511,9 @@ _Document the product capabilities that should exist._
 ## Roadmap Candidate Signals
 
 - [candidate] _Potential modernization or roadmap candidate._
-  - Based on: partial capability | gap | risk | open question | business goal
+  - Domain: _<Domain name>_
   - Related capability: _<name>_
+  - Based on: partial capability | gap | risk | open question | business goal
 `
   },
   codebase: {
@@ -13807,6 +13998,44 @@ function runAdaptersStatus(opts = {}) {
   }
 }
 
+// src/commands/adr.ts
+function runAdr(opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  const td = buildTechDecisions(dir);
+  if (opts.json) {
+    console.log(JSON.stringify(td, null, 2));
+    return;
+  }
+  console.log("");
+  console.log("Tech Decisions");
+  console.log(`  Decision candidates: ${td.candidates}`);
+  console.log(`  ADRs: ${td.adrs} (draft: ${td.draft_adrs}, accepted: ${td.accepted_adrs})`);
+  console.log(`  Status: ${td.status}`);
+  if (td.candidate_list.length > 0 && td.adrs === 0) {
+    console.log("");
+    console.log("ADR candidates found:");
+    td.candidate_list.forEach((c, i) => {
+      console.log("");
+      console.log(`${i + 1}. ${c.title}`);
+      console.log(`   Source: ${c.source}`);
+      console.log(`   Suggested ADR: ${c.suggestedAdrFile}`);
+    });
+    console.log("");
+    console.log("Next:");
+    console.log("  Use the adr-writing skill to create ADR drafts from these candidates");
+    console.log("  (copy context + options; leave the decision/consequences as [open] for human review).");
+  } else if (td.candidates === 0) {
+    console.log("");
+    console.log("No decision candidates found. Run the architecture-agent to produce");
+    console.log("`knowledge/tech/decision-candidates.md`, or add ADRs under `knowledge/tech/decisions/`.");
+  } else {
+    console.log("");
+    console.log("ADRs already exist. Review drafts and mark them `accepted` when confirmed.");
+  }
+  printCommandFooter("adr");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -13860,6 +14089,9 @@ program.command("drift").description("Drift Trend Report from recorded `kaddo gu
 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("adr").alias("decisions").description("List technical decision candidates and the ADR files to create from them (read-only)").option("--json", "Output JSON").action((opts) => {
+  runAdr(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.39.0",
+  "version": "3.40.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {