@kaddo/cli 3.55.0 → 3.57.0

package/dist/index.js

@@ -45,6 +45,7 @@ import * as p from "@clack/prompts";
 var intro2 = (title) => p.intro(title);
 var outro2 = (msg) => p.outro(msg);
 var log2 = p.log;
+var cancel2 = (msg) => p.cancel(msg);
 async function text2(opts) {
   const val = await p.text(opts);
   if (p.isCancel(val)) {
@@ -1145,8 +1146,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path6 = i.path.join(".");
-      return path6 ? `  - ${path6}: ${i.message}` : `  - ${i.message}`;
+      const path7 = i.path.join(".");
+      return path7 ? `  - ${path7}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -6000,7 +6001,7 @@ function parseArtifact(filePath, raw) {
       status: String(data.status ?? ""),
       phase: String(data.phase ?? ""),
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
-      source: data.source ? String(data.source) : "",
+      source: data.source && typeof data.source === "object" ? String(data.source.type ?? "") : data.source ? String(data.source) : "",
       sourceId: String(data.source_id ?? ""),
       rawFrontmatter: data,
       decisions: Array.isArray(data.decisions) ? data.decisions.map(String).filter(Boolean) : [],
@@ -6192,10 +6193,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path6 = join(dir, IGNORE_FILE);
-  if (!exists(path6)) return [];
+  const path7 = join(dir, IGNORE_FILE);
+  if (!exists(path7)) return [];
   try {
-    const raw = readFile(path6);
+    const raw = readFile(path7);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6203,7 +6204,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path6 = join(dir, IGNORE_FILE);
+  const path7 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -6211,17 +6212,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path6, stringifyYaml2(existing));
+  writeFile(path7, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path6 = join(dir, IGNORE_FILE);
+  const path7 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path6, stringifyYaml2(filtered));
+  writeFile(path7, stringifyYaml2(filtered));
   return true;
 }
 
@@ -6243,11 +6244,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path6 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path6)) return [];
+  const path7 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path7)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path6));
+    parsed = parseYaml5(readFile(path7));
   } catch {
     return [];
   }
@@ -6676,7 +6677,7 @@ function buildGuardHistory(dir) {
     const d = hotspotDir(t.code_path);
     hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path6, warnings]) => ({ path: path6, warnings })).sort((a, b) => b.warnings - a.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path7, warnings]) => ({ path: path7, warnings })).sort((a, b) => b.warnings - a.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -7377,7 +7378,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path6, md) {
+function parseCapsule(id, path7, md) {
   const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -7387,7 +7388,7 @@ function parseCapsule(id, path6, md) {
   }
   return {
     id,
-    path: path6,
+    path: path7,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -7473,9 +7474,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path6 = layer2.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path6) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path6 });
+    const path7 = layer2.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path7) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path7 });
       presentLayers.push(layer2.id);
     }
   }
@@ -8983,10 +8984,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const discovery = state === "pre-ai" || state === "legacy";
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path6 = agentInstallPath(file);
-    const installed = isFile(join(dir, path6));
+    const path7 = agentInstallPath(file);
+    const installed = isFile(join(dir, path7));
     const group = agentGroupOf(file);
-    return { agentPath: path6, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path7, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const refine = (id, agent, target, quality, verb = "complete") => {
     const ar = resolveAgent(agent);
@@ -9026,12 +9027,23 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (oq.summary.blocking_open > 0) {
     return { id: "questions", phase: "Knowledge Refinement", label: "Run `kaddo questions` to see source locations and resolution guidance, then resolve, assume or defer the blocking open questions.", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
   }
+  const st = buildDeliveryState(dir);
+  const secondary = buildSecondaryRecommendations(st);
   const roadmap = roadmapSignal(dir);
+  if (roadmap !== "has-candidates" && st.draft_work_items > 0) {
+    return {
+      id: "refine-work-item",
+      phase: "Active Delivery",
+      label: "Refine the existing draft Work Item with the work-item-agent.",
+      agent: "work-item-agent",
+      skill: "work-item-refinement",
+      reason: `There ${st.draft_work_items === 1 ? "is" : "are"} ${st.draft_work_items} draft Work Item${st.draft_work_items === 1 ? "" : "s"}. Refine before defining roadmap candidates.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
   if (roadmap !== "has-candidates") {
     return { id: "roadmap", phase: "Planning", label: "Use roadmap-agent to define roadmap candidates (`kaddo roadmap`).", command: "kaddo roadmap", agent: "roadmap-agent", target: "knowledge/delivery/roadmap.md", reason: "The roadmap has no candidates yet." };
   }
-  const st = buildDeliveryState(dir);
-  const secondary = buildSecondaryRecommendations(st);
   if (st.total_work_items === 0) {
     return {
       id: "create-work-item",
@@ -9400,7 +9412,25 @@ function isValidSource(s) {
   return VALID_SOURCES.includes(s);
 }
 function parseWorkItemSource(frontmatter) {
-  const raw = frontmatter.source ? String(frontmatter.source) : "";
+  const rawSource = frontmatter.source;
+  if (rawSource != null && typeof rawSource === "object" && !Array.isArray(rawSource)) {
+    const obj = rawSource;
+    const t = optStr(obj.type);
+    const type = t && isValidSource(t) ? t : "unknown";
+    return {
+      type,
+      id: optStr(obj.id) ?? optStr(frontmatter.source_id),
+      title: optStr(obj.title) ?? optStr(frontmatter.source_title),
+      context: optStr(obj.context) ?? optStr(frontmatter.source_context),
+      provider: optStr(obj.provider) ?? optStr(frontmatter.source_provider),
+      url: optStr(obj.url) ?? optStr(frontmatter.source_url),
+      imported_at: optStr(obj.imported_at) ?? optStr(frontmatter.source_imported_at),
+      synced_at: optStr(obj.synced_at) ?? optStr(frontmatter.source_synced_at),
+      inferred: obj.inferred === true || obj.inferred === "true",
+      reason: t && !isValidSource(t) ? `Invalid source type in object: "${t}".` : void 0
+    };
+  }
+  const raw = rawSource ? String(rawSource) : "";
   if (raw && isValidSource(raw)) {
     return {
       type: raw,
@@ -12731,10 +12761,10 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
 var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
-  const path6 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path6)) return null;
+  const path7 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path7)) return null;
   try {
-    return parseYaml13(readFile(path6));
+    return parseYaml13(readFile(path7));
   } catch {
     return null;
   }
@@ -14339,10 +14369,10 @@ function slugify4(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path6 = join(dir, DESCRIPTOR_PATH3);
-  if (!exists(path6)) return { version: 1, modules: [] };
+  const path7 = join(dir, DESCRIPTOR_PATH3);
+  if (!exists(path7)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml14(readFile(path6));
+    const parsed = parseYaml14(readFile(path7));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -16410,6 +16440,156 @@ function runAssetsUpdate(kind, opts = {}) {
   outro2(`${LABEL[kind]} update complete.`);
 }
 
+// src/commands/ready.ts
+import fs4 from "fs";
+import path6 from "path";
+import matter11 from "gray-matter";
+function validateReadiness(content, frontmatter) {
+  const warnings = [];
+  const body = content.replace(/^---[\s\S]*?---/, "").trim();
+  const lower = body.toLowerCase();
+  if (!frontmatter.domains || Array.isArray(frontmatter.domains) && frontmatter.domains.length === 0) {
+    warnings.push({ field: "domains", message: "No domains declared." });
+  }
+  const code = frontmatter.code;
+  if (!code || Array.isArray(code) && code.length === 0) {
+    warnings.push({ field: "code", message: "No code ownership globs declared." });
+  }
+  const hasAC = /## acceptance criteria|## criterios de aceptación/i.test(body);
+  if (!hasAC) {
+    warnings.push({ field: "acceptance_criteria", message: "No acceptance criteria section found." });
+  } else {
+    const acSection = extractSection(body, /## acceptance criteria|## criterios de aceptación/i);
+    if (acSection && acSection.trim().length === 0) {
+      warnings.push({ field: "acceptance_criteria", message: "Acceptance criteria section is empty." });
+    }
+  }
+  const hasValidation = /## validation|## validación/i.test(body);
+  if (!hasValidation) {
+    warnings.push({ field: "validation", message: "No validation section found." });
+  }
+  const hasOQ = /## open questions|## preguntas abiertas/i.test(body);
+  if (hasOQ) {
+    const oqSection = extractSection(body, /## open questions|## preguntas abiertas/i);
+    if (oqSection && !isResolvedSection(oqSection)) {
+      warnings.push({ field: "open_questions", message: "Open questions are still present." });
+    }
+  }
+  return warnings;
+}
+function extractSection(body, headerPattern) {
+  const lines = body.split(/\r?\n/);
+  let capture = false;
+  const result = [];
+  for (const line of lines) {
+    if (capture) {
+      if (/^#{1,3}\s/.test(line)) break;
+      result.push(line);
+    } else if (headerPattern.test(line)) {
+      capture = true;
+    }
+  }
+  return capture ? result.join("\n").trim() : null;
+}
+function isResolvedSection(text3) {
+  const t = text3.trim().toLowerCase();
+  return t === "" || /^(none|ninguna|resolved|resueltas|deferred|diferidas)\.?$/i.test(t);
+}
+function transitionToReady(filePath) {
+  const raw = readFile(filePath);
+  const { data, content } = matter11(raw);
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  data.status = "ready";
+  data.ready_at = today2;
+  const newContent = matter11.stringify(content, data);
+  const posix = filePath.replace(/\\/g, "/");
+  let newPath = filePath;
+  if (posix.includes("/work-items/draft/")) {
+    const readyDir = path6.dirname(filePath).replace(/[/\\]draft$/, path6.sep + "ready");
+    ensureDir(readyDir);
+    const fileName = path6.basename(filePath);
+    newPath = path6.join(readyDir, fileName);
+  }
+  return { newPath, newContent };
+}
+function findWorkItem(dir, id) {
+  const wis = discoverWorkItems(dir);
+  return wis.find((w) => w.id.toLowerCase() === id.toLowerCase()) ?? null;
+}
+async function runReady(id, opts = {}) {
+  const dir = process.cwd();
+  intro2("kaddo ready " + id);
+  const config = loadConfig(dir);
+  if (!config) {
+    log2.error("Kaddo is not initialized. Run `kaddo init` first.");
+    process.exit(1);
+  }
+  const wi = findWorkItem(dir, id);
+  if (!wi) {
+    log2.error(`Work Item ${id} not found.`);
+    log2.info("Run `kaddo history` or check knowledge/delivery/work-items/ for available IDs.");
+    process.exit(1);
+  }
+  if (wi.lifecycle === "ready") {
+    log2.info(`Work Item ${wi.id} is already ready.`);
+    log2.info("Suggested next: kaddo context && kaddo understand");
+    outro2("Nothing to do.");
+    return;
+  }
+  if (wi.lifecycle !== "draft") {
+    log2.error(`Work Item ${wi.id} is in state "${wi.lifecycle}", not "draft". Only draft Work Items can be marked as ready.`);
+    process.exit(1);
+  }
+  const raw = readFile(wi.filePath);
+  const { data } = matter11(raw);
+  const source = parseWorkItemSource(data);
+  const warnings = validateReadiness(raw, data);
+  log2.info(`Work Item found:`);
+  log2.info(`  ${wi.id} \u2014 ${wi.title}`);
+  log2.info("");
+  log2.info(`  Status: draft \u2192 ready`);
+  log2.info(`  Type: ${wi.type}`);
+  log2.info(`  Knowledge level: ${wi.knowledgeLevel || "unset"}`);
+  log2.info(`  Domains: ${wi.domains.length > 0 ? wi.domains.join(", ") : "none"}`);
+  log2.info(`  Source: ${renderSourceCompact(source)}`);
+  if (wi.codeGlobs.length > 0) {
+    log2.info(`  Code ownership:`);
+    for (const g of wi.codeGlobs) log2.info(`    - ${g}`);
+  } else {
+    log2.info(`  Code ownership: none`);
+  }
+  if (warnings.length > 0) {
+    log2.warn("");
+    log2.warn("This Work Item may not be ready:");
+    for (const w of warnings) {
+      log2.warn(`  - ${w.message}`);
+    }
+  }
+  if (!opts.yes) {
+    log2.info("");
+    const proceed = await confirm2({ message: "Mark this Work Item as ready for implementation?" });
+    if (!proceed) {
+      cancel2("Cancelled.");
+      return;
+    }
+  }
+  const { newPath, newContent } = transitionToReady(wi.filePath);
+  if (newPath !== wi.filePath) {
+    writeFile(newPath, newContent);
+    fs4.unlinkSync(wi.filePath);
+    log2.success(`Updated status: ready`);
+    log2.success(`Moved file:`);
+    log2.info(`  ${path6.relative(dir, wi.filePath)}`);
+    log2.info(`  \u2192 ${path6.relative(dir, newPath)}`);
+  } else {
+    writeFile(wi.filePath, newContent);
+    log2.success(`Updated status: ready`);
+  }
+  log2.info("");
+  log2.info("Run `kaddo context && kaddo understand` to refresh the handoff.");
+  outro2(`Work Item ${wi.id} is ready.`);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -16427,12 +16607,15 @@ program.command("bootstrap").description("Build the initial knowledge base for a
 program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike, chore). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
   await runCreate(type ?? "", opts);
 });
+program.command("ready <id>").description("Mark a draft Work Item as ready for implementation after human review").option("--yes", "Skip confirmation prompt").action(async (id, opts) => {
+  await runReady(id, opts);
+});
 var capsuleCmd = program.command("capsule").description("Export this project as a Knowledge Capsule, or import an external one as context");
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").action(() => {
   runCapsuleExport();
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path6) => {
-  runCapsuleAdd(path6);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path7) => {
+  runCapsuleAdd(path7);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {

package/package.json

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