@kaddo/cli 3.40.0 → 3.41.0

package/README.md

@@ -538,6 +538,8 @@ create --from roadmap → owners → guard → explain`.
 | 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 |
+| v3.40.1 | ADR slug cleanup + MCP: suggested ADR filenames strip list/heading prefixes (no `ADR-001-1-…`) and normalize acronyms; new read-only MCP resource `kaddo://tech-decisions` sharing `buildTechDecisions` with `kaddo adr` |
+| v3.41 | Tech knowledge structure: `knowledge/tech/discovery/` for architecture-notes/decision-candidates (core vs decisions vs discovery); `kaddo adr` reads discovery-first with legacy fallback; `kaddo tech organize` migrates safely; `explain` shows `## Tech Knowledge` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -708,6 +708,10 @@ var COMMAND_HELP = {
   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"
+  },
+  "tech organize": {
+    question: "Is knowledge/tech/ cleanly separated (core vs discovery vs decisions)?",
+    next: "Discovery notes now live under knowledge/tech/discovery/"
   }
 };
 function commandFooterLines(name) {
@@ -2439,9 +2443,9 @@ Optionally provide: existing diagrams, infra config, README, dependency manifest
 
 Markdown artifacts intended to be saved as:
 
-- \`knowledge/tech/current-state.md\`
-- \`knowledge/tech/architecture-notes.md\`
-- \`knowledge/tech/decision-candidates.md\`
+- \`knowledge/tech/current-state.md\` (core artifact)
+- \`knowledge/tech/discovery/architecture-notes.md\` (discovery note)
+- \`knowledge/tech/discovery/decision-candidates.md\` (discovery input for ADRs)
 
 ## Instructions
 
@@ -2487,10 +2491,12 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the architecture overview as \`knowledge/tech/current-state.md\`, supporting notes as
-\`knowledge/tech/architecture-notes.md\`, and decision candidates as
-\`knowledge/tech/decision-candidates.md\`. Final ADRs always live under
-\`knowledge/tech/decisions/\` \u2014 never directly in \`knowledge/tech/\`.
+Save the architecture overview as \`knowledge/tech/current-state.md\` (a **core** artifact). Save
+supporting notes as \`knowledge/tech/discovery/architecture-notes.md\` and decision candidates as
+\`knowledge/tech/discovery/decision-candidates.md\` \u2014 **discovery** inputs live under
+\`knowledge/tech/discovery/\`, not directly in \`knowledge/tech/\` (VS-075.2). Final ADRs always live
+under \`knowledge/tech/decisions/\`. Kaddo still reads the legacy root locations for backward
+compatibility, but new output should use \`discovery/\`.
 
 ## Quality Checklist
 
@@ -8123,18 +8129,31 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/core/decisions.ts
-var CANDIDATES_PATH = "knowledge/tech/decision-candidates.md";
+var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
+var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
 var DECISIONS_DIR = "knowledge/tech/decisions";
+function resolveCandidatesPath(dir) {
+  const discovery = exists(join(dir, CANDIDATES_DISCOVERY));
+  const legacy = exists(join(dir, CANDIDATES_LEGACY));
+  if (discovery) return { path: CANDIDATES_DISCOVERY, legacy: false, bothExist: legacy };
+  if (legacy) return { path: CANDIDATES_LEGACY, legacy: true, bothExist: false };
+  return { path: null, legacy: false, bothExist: false };
+}
+function cleanCandidateTitle(title) {
+  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
+}
 function slugify2(s) {
-  return s.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return cleanCandidateTitle(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
 }
 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);
+      const raw = m[1].trim();
+      if (!raw || /^_.*_$/.test(raw)) continue;
+      const t = cleanCandidateTitle(raw);
+      if (t) out.push(t);
     }
   }
   return out;
@@ -8163,11 +8182,11 @@ function countAdrs(dir) {
   return { total, draft, accepted };
 }
 function buildTechDecisions(dir) {
-  const candFile = join(dir, CANDIDATES_PATH);
+  const resolved = resolveCandidatesPath(dir);
   let titles = [];
-  if (exists(candFile)) {
+  if (resolved.path) {
     try {
-      titles = parseDecisionCandidates(readFile(candFile));
+      titles = parseDecisionCandidates(readFile(join(dir, resolved.path)));
     } catch {
       titles = [];
     }
@@ -8175,7 +8194,7 @@ function buildTechDecisions(dir) {
   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` };
+    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
   });
   let status;
   if (accepted > 0) status = "accepted-adrs";
@@ -8188,7 +8207,10 @@ function buildTechDecisions(dir) {
     adrs: total,
     draft_adrs: draft,
     accepted_adrs: accepted,
-    candidate_list
+    candidate_list,
+    candidates_source: resolved.path,
+    candidates_legacy_location: resolved.legacy,
+    candidates_both_exist: resolved.bothExist
   };
 }
 
@@ -8404,7 +8426,18 @@ function buildProjectExplanation(dir) {
     suggestedNextSteps,
     readiness,
     nextStepRecommendation: readiness.nextStepRecommendation,
-    techDecisions: buildTechDecisions(dir)
+    techDecisions: buildTechDecisions(dir),
+    techKnowledge: {
+      core: {
+        currentState: exists(join(dir, "knowledge/tech/current-state.md")),
+        codebase: exists(join(dir, "knowledge/tech/codebase.md"))
+      },
+      discovery: {
+        architectureNotes: exists(join(dir, "knowledge/tech/discovery/architecture-notes.md")) || exists(join(dir, "knowledge/tech/architecture-notes.md")),
+        decisionCandidates: exists(join(dir, "knowledge/tech/discovery/decision-candidates.md")) || exists(join(dir, "knowledge/tech/decision-candidates.md")),
+        legacyLocation: exists(join(dir, "knowledge/tech/architecture-notes.md")) || exists(join(dir, "knowledge/tech/decision-candidates.md"))
+      }
+    }
   };
 }
 function stateLabel(state) {
@@ -8619,15 +8652,26 @@ function renderExplanationHuman(exp) {
   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}`);
+  const tk = exp.techKnowledge;
+  const mark = (b) => b ? "\u2713" : "\u2717";
+  lines.push("## Tech Knowledge");
+  lines.push("Core:");
+  lines.push(`- ${mark(tk.core.currentState)} current-state.md`);
+  lines.push(`- ${mark(tk.core.codebase)} codebase.md`);
+  lines.push("Decisions:");
+  lines.push(`- ADRs: ${td.adrs} (draft: ${td.draft_adrs}, accepted: ${td.accepted_adrs}) \xB7 status: ${td.status}`);
+  lines.push("Discovery:");
+  lines.push(`- ${mark(tk.discovery.architectureNotes)} architecture-notes.md`);
+  lines.push(`- ${mark(tk.discovery.decisionCandidates)} decision-candidates.md`);
+  lines.push("");
   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("");
+  }
+  if (tk.discovery.legacyLocation) {
+    lines.push("Tech discovery files are in the legacy `knowledge/tech/` root. Suggested cleanup: run `kaddo tech organize`.");
+    lines.push("");
   }
-  lines.push("");
   return lines.join("\n").trimEnd() + "\n";
 }
 function renderExplanationAgent(exp) {
@@ -8976,6 +9020,22 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   if (techDecisions.candidates > 0 && techDecisions.adrs === 0) {
     missing.push(`${techDecisions.candidates} technical decision candidate(s) not yet materialized as ADRs (run \`kaddo adr\`).`);
   }
+  const techFile = (rel) => exists(join(dir, ARCH_DIR6, rel));
+  const techKnowledge = {
+    core: {
+      "current-state.md": techFile("tech/current-state.md"),
+      "codebase.md": techFile("tech/codebase.md")
+    },
+    decisions: { adrs: techDecisions.adrs, dir: exists(join(dir, ARCH_DIR6, "tech/decisions")) },
+    discovery: {
+      "architecture-notes.md": techFile("tech/discovery/architecture-notes.md") || techFile("tech/architecture-notes.md"),
+      "decision-candidates.md": techFile("tech/discovery/decision-candidates.md") || techFile("tech/decision-candidates.md"),
+      legacyLocation: techFile("tech/architecture-notes.md") || techFile("tech/decision-candidates.md")
+    }
+  };
+  if (techKnowledge.discovery.legacyLocation) {
+    missing.push("Tech discovery files are in the legacy `knowledge/tech/` root. Run `kaddo tech organize` to move them to `knowledge/tech/discovery/`.");
+  }
   const unifiedPhase = {
     ...phase,
     nextStep: nextStepRecommendation.label,
@@ -9014,6 +9074,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     phase: unifiedPhase,
     nextStepRecommendation,
     techDecisions,
+    techKnowledge,
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -12720,7 +12781,7 @@ var FILE_TARGETS = [
   { path: "knowledge/tech/current-state.md", kind: "current-state" },
   { path: "knowledge/delivery/roadmap.md", kind: "roadmap" }
 ];
-var DIR_TARGETS = ["knowledge/tech/decisions", "knowledge/delivery/work-items"];
+var DIR_TARGETS = ["knowledge/tech/decisions", "knowledge/tech/discovery", "knowledge/delivery/work-items"];
 function withLanguageDirective(content, language) {
   if (language !== "es") return content;
   const note = "> Idioma del proyecto: **espa\xF1ol**. Escribe este conocimiento en espa\xF1ol. Mant\xE9n en ingl\xE9s el c\xF3digo, los nombres de archivo, los comandos y las claves de configuraci\xF3n.\n";
@@ -14012,6 +14073,15 @@ function runAdr(opts = {}) {
   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.candidates_source) console.log(`  Source: ${td.candidates_source}`);
+  if (td.candidates_both_exist) {
+    console.log("");
+    console.log("  Note: both decision-candidate files exist.");
+    console.log("    Using: knowledge/tech/discovery/decision-candidates.md");
+    console.log("    Legacy file also found: knowledge/tech/decision-candidates.md");
+  } else if (td.candidates_legacy_location) {
+    console.log("  (legacy location \u2014 consider `kaddo tech organize` to move it to knowledge/tech/discovery/)");
+  }
   if (td.candidate_list.length > 0 && td.adrs === 0) {
     console.log("");
     console.log("ADR candidates found:");
@@ -14036,6 +14106,41 @@ function runAdr(opts = {}) {
   printCommandFooter("adr");
 }
 
+// src/commands/tech.ts
+import fs3 from "fs";
+var DISCOVERY_FILES = ["architecture-notes.md", "decision-candidates.md"];
+var DISCOVERY_DIR = "knowledge/tech/discovery";
+function runTechOrganize(dir = cwd()) {
+  requireConfig(dir);
+  intro2("kaddo tech organize");
+  const moved = [];
+  const skipped = [];
+  for (const file of DISCOVERY_FILES) {
+    const from = join(dir, "knowledge/tech", file);
+    const to = join(dir, DISCOVERY_DIR, file);
+    if (!exists(from)) continue;
+    if (exists(to)) {
+      skipped.push(file);
+      continue;
+    }
+    ensureDir(join(dir, DISCOVERY_DIR));
+    fs3.renameSync(from, to);
+    moved.push(`knowledge/tech/${file} \u2192 ${DISCOVERY_DIR}/${file}`);
+  }
+  if (moved.length > 0) {
+    log2.success("Moved:");
+    for (const m of moved) console.log(`  - ${m}`);
+  }
+  for (const file of skipped) {
+    log2.warn(`Cannot move ${file} because knowledge/tech/discovery/${file} already exists. Review both files manually.`);
+  }
+  if (moved.length === 0 && skipped.length === 0) {
+    log2.info("Nothing to organize \u2014 no discovery files in the legacy `knowledge/tech/` root.");
+  }
+  printCommandFooter("tech organize");
+  outro2("Tech knowledge organized.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -14089,6 +14194,10 @@ 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);
+var techCmd = program.command("tech").description("Organize the knowledge/tech/ structure (core vs discovery vs decisions)");
+techCmd.command("organize").description("Move discovery artifacts into knowledge/tech/discovery/ (never overwrites, no content change)").action(() => {
+  runTechOrganize();
+});
 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);
 });

package/package.json

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