@kaddo/cli 3.56.0 → 3.58.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}`);
@@ -2231,6 +2232,8 @@ validation (how to test it), definition of done, open questions and dependencies
 - Do not expand scope without explicit confirmation.
 - Do not create mega Work Items \u2014 split when it covers multiple outcomes.
 - Keep acceptance criteria testable.
+- This skill refines scope and acceptance criteria but does not approve implementation readiness.
+  Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
 
 ## Quality checklist
 
@@ -2636,9 +2639,9 @@ var RESPONSIBILITY_MATRIX = {
     agent: "work-item-agent",
     responsibleFor: ["Work Item refinement"],
     produces: ["knowledge/delivery/work-items/"],
-    canSuggest: ["implementation-agent"],
+    canSuggest: ["kaddo ready", "mark_work_item_ready", "implementation-agent"],
     cannotSuggest: ["branches", "commits", "pull requests", "code"],
-    next: ["implementation-agent"]
+    next: ["kaddo ready (human review)", "implementation-agent"]
   },
   "implementation-agent": {
     agent: "implementation-agent",
@@ -3651,7 +3654,16 @@ and \`blocked\` as active work; \`completed\` and \`archived\` are historical kn
 
 ## Handoff
 
-When the Work Item is refined and ready to build, **hand off to the implementation-agent**.
+After refining a Work Item, **do not mark it ready automatically**. If the Work Item appears
+complete (acceptance criteria, validation, code globs, domains all present, open questions
+resolved), recommend human review and the ready transition:
+
+- **CLI:** \`kaddo ready <WI-ID>\`
+- **MCP:** \`mark_work_item_ready({ id: "<WI-ID>" })\`
+
+The transition to \`ready\` requires explicit human confirmation. Only after a human marks the
+Work Item as ready should it be handed off to the implementation-agent.
+
 You do **not** suggest branches, commits or pull requests \u2014 implementation (including any Git
 branch suggestion) is the implementation-agent's responsibility, and only by respecting the
 project Git strategy. Your job ends at a clear, traceable Work Item that **states how to test it**.
@@ -6000,7 +6012,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 +6204,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 +6215,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 +6223,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 +6255,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 +6688,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 +7389,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 +7399,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 +7485,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);
     }
   }
@@ -8903,6 +8915,7 @@ function buildDeliveryState(dir) {
   return {
     phase: "",
     draft_work_items: byState("draft"),
+    refined_draft_work_items: wis.filter((w) => w.lifecycle === "draft" && w.rawFrontmatter.refined_by).length,
     ready_work_items: byState("ready"),
     in_progress_work_items: byState("in-progress"),
     blocked_work_items: byState("blocked"),
@@ -8983,10 +8996,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);
@@ -9030,6 +9043,17 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const secondary = buildSecondaryRecommendations(st);
   const roadmap = roadmapSignal(dir);
   if (roadmap !== "has-candidates" && st.draft_work_items > 0) {
+    if (st.refined_draft_work_items > 0) {
+      return {
+        id: "review-work-item",
+        phase: "Active Delivery",
+        label: "Review the refined draft Work Item and mark it ready with `kaddo ready`.",
+        command: "kaddo ready",
+        mcpAction: "kaddo_mark_work_item_ready",
+        reason: `There ${st.refined_draft_work_items === 1 ? "is" : "are"} ${st.refined_draft_work_items} refined draft Work Item${st.refined_draft_work_items === 1 ? "" : "s"} awaiting human review.`,
+        ...secondary.length ? { secondary } : {}
+      };
+    }
     return {
       id: "refine-work-item",
       phase: "Active Delivery",
@@ -9835,7 +9859,8 @@ function mapNextStepId(id) {
     "refine-product": "define-product",
     "refine-capabilities": "discover-capabilities",
     "refine-current-state": "describe-architecture",
-    "refine-codebase": "describe-architecture"
+    "refine-codebase": "describe-architecture",
+    "review-work-item": "refine-work-item"
   };
   return MAP[id] ?? id;
 }
@@ -12760,10 +12785,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;
   }
@@ -14368,10 +14393,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: [] };
@@ -16439,6 +16464,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");
@@ -16456,12 +16631,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.56.0",
+  "version": "3.58.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {