@kaddo/cli 3.40.1 → 3.42.0

package/README.md

@@ -539,6 +539,8 @@ create --from roadmap → owners → guard → explain`.
 | 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` |
+| v3.42 | Agent & skill version metadata: installed agents/skills carry a `version:`; `kaddo agents status` / `kaddo skills status` classify up-to-date/outdated/unknown-version/modified/missing; `agents update` / `skills update` refresh outdated safely (never overwrite edits without `--force`); MCP `kaddo://installed-assets` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -708,6 +708,18 @@ 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/"
+  },
+  "agents status": {
+    question: "Are the installed agents aligned with the current Kaddo version?",
+    next: "Run `kaddo agents update` to refresh outdated agents"
+  },
+  "skills status": {
+    question: "Are the installed skills aligned with the current Kaddo version?",
+    next: "Run `kaddo skills update` to refresh outdated skills"
   }
 };
 function commandFooterLines(name) {
@@ -1511,14 +1523,38 @@ var guardAdvancedModule = {
   ]
 };
 
+// src/core/version.ts
+import { fileURLToPath } from "url";
+import { dirname, join as join2, parse } from "path";
+import { existsSync, readFileSync } from "fs";
+function resolveVersion() {
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const root = parse(dir).root;
+    for (; ; ) {
+      const pkg = join2(dir, "package.json");
+      if (existsSync(pkg)) {
+        const v = JSON.parse(readFileSync(pkg, "utf-8")).version;
+        if (v) return v;
+      }
+      if (dir === root) break;
+      dir = dirname(dir);
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+var KADDO_VERSION = resolveVersion();
+
 // src/skills/skills.ts
 function skill(id, title, group, appliesTo, body) {
   const frontMatter2 = [
     "---",
     "type: skill",
     `id: ${id}`,
+    `name: ${id}`,
     `title: ${title}`,
-    "version: 1",
+    `version: ${KADDO_VERSION}`,
     `group: ${group}`,
     "applies_to:",
     ...appliesTo.map((a) => `  - ${a}`),
@@ -2439,9 +2475,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 +2523,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
 
@@ -4044,6 +4082,19 @@ function selectAgentFiles(opts) {
 }
 
 // src/modules/agents.ts
+function withAgentFrontMatter(fileName, content) {
+  const name = fileName.replace(/\.md$/, "");
+  const fm2 = [
+    "---",
+    "type: agent",
+    `name: ${name}`,
+    `version: ${KADDO_VERSION}`,
+    `group: ${agentGroupOf(fileName)}`,
+    "---",
+    ""
+  ].join("\n");
+  return fm2 + content.replace(/^\s+/, "");
+}
 var agentReadme = {
   path: "knowledge/agents/README.md",
   content: [
@@ -4115,7 +4166,7 @@ var agentReadme = {
 };
 var agentFiles = AGENT_PROMPTS.map((a) => ({
   path: agentInstallPath(a.fileName),
-  content: a.content
+  content: withAgentFrontMatter(a.fileName, a.content)
 }));
 var agentsModule = {
   name: "agents",
@@ -6196,7 +6247,7 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
@@ -8123,8 +8174,16 @@ 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();
 }
@@ -8168,11 +8227,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 = [];
     }
@@ -8180,7 +8239,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";
@@ -8193,10 +8252,79 @@ 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
   };
 }
 
+// src/core/assets.ts
+import matter4 from "gray-matter";
+function canonicalAgents() {
+  return AGENT_PROMPTS.map((a) => ({
+    name: a.fileName.replace(/\.md$/, ""),
+    path: agentInstallPath(a.fileName),
+    content: withAgentFrontMatter(a.fileName, a.content)
+  }));
+}
+function canonicalSkills() {
+  return SKILLS.map((s) => ({ name: s.id, path: skillInstallPath(s.id), content: s.content }));
+}
+function versionOf(content) {
+  try {
+    const v = matter4(content).data.version;
+    return v === void 0 || v === null ? null : String(v);
+  } catch {
+    return null;
+  }
+}
+function cmpVersion(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function classify(dir, asset) {
+  const full = join(dir, asset.path);
+  const base = { name: asset.name, path: asset.path, available: KADDO_VERSION };
+  if (!exists(full)) return { ...base, installed: null, state: "missing" };
+  let content = "";
+  try {
+    content = readFile(full);
+  } catch {
+    return { ...base, installed: null, state: "missing" };
+  }
+  const installed = versionOf(content);
+  if (installed === null) return { ...base, installed: null, state: "unknown-version" };
+  const cmp = cmpVersion(installed, KADDO_VERSION);
+  if (cmp < 0) return { ...base, installed, state: "outdated" };
+  if (content.trim() !== asset.content.trim()) return { ...base, installed, state: "modified" };
+  return { ...base, installed, state: "up-to-date" };
+}
+function summarize(items) {
+  const count = (s) => items.filter((i) => i.state === s).length;
+  return {
+    total: items.length,
+    up_to_date: count("up-to-date"),
+    outdated: count("outdated"),
+    missing: count("missing"),
+    unknown_version: count("unknown-version"),
+    modified: count("modified"),
+    items
+  };
+}
+function assetStatus(dir, kind) {
+  const catalog = kind === "agent" ? canonicalAgents() : canonicalSkills();
+  return summarize(catalog.map((a) => classify(dir, a)));
+}
+function installedAssetsSummary(dir) {
+  return { version: KADDO_VERSION, agents: assetStatus(dir, "agent"), skills: assetStatus(dir, "skill") };
+}
+
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
 function normalizeTitle(t) {
@@ -8409,7 +8537,19 @@ 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"))
+      }
+    },
+    installedAssets: installedAssetsSummary(dir)
   };
 }
 function stateLabel(state) {
@@ -8624,15 +8764,41 @@ 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("");
+  }
+  const ia = exp.installedAssets;
+  const agentsInstalled = ia.agents.total - ia.agents.missing;
+  const skillsInstalled = ia.skills.total - ia.skills.missing;
+  if (agentsInstalled > 0 || skillsInstalled > 0) {
+    const issues = (s2) => [s2.outdated ? `${s2.outdated} outdated` : "", s2.unknown_version ? `${s2.unknown_version} unknown-version` : "", s2.modified ? `${s2.modified} modified` : ""].filter(Boolean).join(", ");
+    lines.push("## Installed Assets");
+    lines.push(`- CLI version: ${ia.version}`);
+    lines.push(`- Agents: ${agentsInstalled} installed${issues(ia.agents) ? ` (${issues(ia.agents)})` : ""}`);
+    lines.push(`- Skills: ${skillsInstalled} installed${issues(ia.skills) ? ` (${issues(ia.skills)})` : ""}`);
+    if (ia.agents.outdated + ia.agents.unknown_version + ia.skills.outdated + ia.skills.unknown_version > 0) {
+      lines.push("");
+      lines.push("Suggested: run `kaddo agents status` and `kaddo skills status`.");
+    }
+    lines.push("");
   }
-  lines.push("");
   return lines.join("\n").trimEnd() + "\n";
 }
 function renderExplanationAgent(exp) {
@@ -8648,7 +8814,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter4(raw);
+    const { data, content } = matter5(raw);
     return { content, data };
   } catch {
     return null;
@@ -8659,7 +8825,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter4(raw);
+    const { content } = matter5(raw);
     return content.trim();
   } catch {
     return null;
@@ -8828,7 +8994,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -8841,7 +9007,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph2(markdown) {
-  const body = matter5(markdown).content.trim();
+  const body = matter6(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -8981,6 +9147,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,
@@ -9019,6 +9201,12 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     phase: unifiedPhase,
     nextStepRecommendation,
     techDecisions,
+    techKnowledge,
+    installedAssets: (() => {
+      const s = installedAssetsSummary(dir);
+      const compact = (a) => ({ total: a.total, installed: a.total - a.missing, outdated: a.outdated, unknown_version: a.unknown_version, modified: a.modified });
+      return { version: s.version, agents: compact(s.agents), skills: compact(s.skills) };
+    })(),
     deliveryMix,
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
@@ -9560,6 +9748,17 @@ function runUnderstand() {
     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`).");
   }
+  const ia = exp.installedAssets;
+  const outdatedRecommended = ia.agents.items.filter(
+    (a) => (a.state === "outdated" || a.state === "unknown-version") && assessment.recommendedAgents.includes(a.name)
+  );
+  if (outdatedRecommended.length > 0) {
+    console.log("");
+    for (const a of outdatedRecommended) {
+      console.log(`Recommended agent ${a.name} is ${a.state} (installed ${a.installed ?? "unknown"}, available ${a.available}).`);
+    }
+    console.log("  \u2192 Run `kaddo agents update` or review `kaddo agents status`.");
+  }
   if (exp.externalCapsules.length > 0) {
     console.log("");
     console.log("External knowledge:");
@@ -9720,7 +9919,7 @@ var DECLARED_LEVEL = {
   incident: "K2",
   rfc: "K3"
 };
-function classify(declaredType, declaredLevel, touchedFiles) {
+function classify2(declaredType, declaredLevel, touchedFiles) {
   const signals = detectSignals(touchedFiles);
   const observedLevel = highestLevel(signals);
   const expectedLevel = DECLARED_LEVEL[declaredType] ?? declaredLevel ?? "K2";
@@ -9800,7 +9999,7 @@ async function runClassify(opts = {}) {
     return;
   }
   if (opts.type) {
-    const result2 = classify(opts.type, opts.level ?? "", touchedFiles);
+    const result2 = classify2(opts.type, opts.level ?? "", touchedFiles);
     printResult2(result2);
     return;
   }
@@ -9811,7 +10010,7 @@ async function runClassify(opts = {}) {
     console.log("Or create one with: kaddo create <type>");
     return;
   }
-  const result = classify(activeItem.type, activeItem.knowledgeLevel, touchedFiles);
+  const result = classify2(activeItem.type, activeItem.knowledgeLevel, touchedFiles);
   printResult2(result, activeItem.id || activeItem.title);
 }
 
@@ -9880,7 +10079,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -9892,7 +10091,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter6(raw);
+  const { data, content } = matter7(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -9917,7 +10116,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter6.stringify(updatedContent, data);
+  const newRaw = matter7.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -10167,7 +10366,7 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
 function normalizeGlob(input) {
   let g = input.trim().replace(/\\/g, "/");
@@ -10289,11 +10488,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter7(raw);
+  const parsed = matter8(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter7.stringify(parsed.content, data);
+  return matter8.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -12725,7 +12924,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";
@@ -12905,7 +13104,7 @@ function runGraphExport(opts = {}) {
 }
 
 // src/core/impact-report.ts
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 function isBroadGlob(glob) {
   if (!glob.endsWith("/**")) return false;
   const prefix = glob.slice(0, -3);
@@ -12974,7 +13173,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter8(readFile(wi.filePath)).content;
+      const body = matter9(readFile(wi.filePath)).content;
       if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
       else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
       if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -14017,6 +14216,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:");
@@ -14041,6 +14249,105 @@ 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/commands/assets.ts
+var LABEL = { agent: "Agents", skill: "Skills" };
+function runAssetsStatus(kind, opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  const summary = assetStatus(dir, kind);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log("");
+  console.log(LABEL[kind]);
+  console.log("");
+  const installed = summary.items.filter((i) => i.state !== "missing");
+  for (const a of installed) {
+    console.log(`${a.path}`);
+    console.log(`  Name: ${a.name}`);
+    console.log(`  Installed: ${a.installed ?? "unknown"}`);
+    console.log(`  Available: ${a.available}`);
+    console.log(`  Status: ${a.state}`);
+    console.log("");
+  }
+  if (installed.length === 0) console.log(`No ${kind}s installed. Run \`kaddo add ${kind}s\`.`);
+  console.log(
+    `Summary: ${summary.up_to_date} up-to-date, ${summary.outdated} outdated, ${summary.unknown_version} unknown-version, ${summary.modified} modified, ${summary.missing} not installed.`
+  );
+  if (summary.outdated > 0 || summary.unknown_version > 0) {
+    console.log(`Run \`kaddo ${kind}s update\` to refresh outdated ${kind}s (\`--force\` for unknown/modified).`);
+  }
+  printCommandFooter(`${kind}s status`);
+}
+function runAssetsUpdate(kind, opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  intro2(`kaddo ${kind}s update`);
+  const summary = assetStatus(dir, kind);
+  const catalog = kind === "agent" ? canonicalAgents() : canonicalSkills();
+  const byPath = new Map(catalog.map((a) => [a.path, a.content]));
+  const updated = [];
+  const skipped = [];
+  for (const item of summary.items) {
+    const canonical = byPath.get(item.path);
+    if (!canonical) continue;
+    const safe = item.state === "outdated";
+    const needsForce = item.state === "unknown-version" || item.state === "modified";
+    if (safe || needsForce && opts.force) {
+      writeFile(join(dir, item.path), canonical);
+      updated.push(`${item.path} (${item.installed ?? "unknown"} \u2192 ${item.available})`);
+    } else if (needsForce) {
+      skipped.push(`${item.path} \u2014 ${item.state} (use --force to overwrite local changes)`);
+    }
+  }
+  if (updated.length > 0) {
+    log2.success("Updated:");
+    for (const u of updated) console.log(`  - ${u}`);
+  } else {
+    log2.info(`No ${kind}s to update.`);
+  }
+  for (const s of skipped) log2.warn(`Skipped ${s}`);
+  if (summary.missing > 0) log2.info(`${summary.missing} ${kind}(s) not installed \u2014 run \`kaddo add ${kind}s\` to add them.`);
+  printCommandFooter(`${kind}s status`);
+  outro2(`${LABEL[kind]} update complete.`);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -14094,6 +14401,16 @@ 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 agentsCmd = program.command("agents").description("Inspect and update installed Kaddo agents (version status)");
+agentsCmd.command("status").description("Show installed agents, their version and whether they are up to date").option("--json", "Output JSON").action((opts) => runAssetsStatus("agent", opts));
+agentsCmd.command("update").description("Refresh outdated agents (never overwrites modified files without --force)").option("--force", "Overwrite unknown-version / locally-modified agents").action((opts) => runAssetsUpdate("agent", opts));
+var skillsCmd = program.command("skills").description("Inspect and update installed Kaddo skills (version status)");
+skillsCmd.command("status").description("Show installed skills, their version and whether they are up to date").option("--json", "Output JSON").action((opts) => runAssetsStatus("skill", opts));
+skillsCmd.command("update").description("Refresh outdated skills (never overwrites modified files without --force)").option("--force", "Overwrite unknown-version / locally-modified skills").action((opts) => runAssetsUpdate("skill", opts));
+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.1",
+  "version": "3.42.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {