@kaddo/cli 3.39.1 → 3.40.0

package/README.md

@@ -537,6 +537,7 @@ create --from roadmap → owners → guard → 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>
 \`\`\`
 `
 );
@@ -2935,6 +2958,13 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 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
@@ -3511,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
@@ -8086,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) {
@@ -8297,7 +8403,8 @@ function buildProjectExplanation(dir) {
     missingKnowledge,
     suggestedNextSteps,
     readiness,
-    nextStepRecommendation: readiness.nextStepRecommendation
+    nextStepRecommendation: readiness.nextStepRecommendation,
+    techDecisions: buildTechDecisions(dir)
   };
 }
 function stateLabel(state) {
@@ -8511,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) {
@@ -8855,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,
@@ -8892,6 +9013,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase: unifiedPhase,
     nextStepRecommendation,
+    techDecisions,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -9315,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);
@@ -9426,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:");
@@ -11940,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) {
@@ -11960,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,
@@ -13869,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");
@@ -13922,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.1",
+  "version": "3.40.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {