@kaddo/mcp 3.56.0 → 3.58.0

package/dist/index.js

@@ -111,6 +111,36 @@ function writeDerived(root, relPath, content) {
   fs.mkdirSync(path.dirname(abs), { recursive: true });
   fs.writeFileSync(abs, content, "utf-8");
 }
+function writeWorkItemTransition(root, relPath, content) {
+  const p = toPosix(relPath).replace(/^\/+/, "");
+  if (path.isAbsolute(relPath) || p.split("/").some((seg) => seg === "..")) {
+    throw new KaddoMcpError("Blocked unsafe work-item write path.");
+  }
+  if (!p.startsWith("knowledge/delivery/work-items/")) {
+    throw new KaddoMcpError("Work Item transitions can only write under knowledge/delivery/work-items/.");
+  }
+  if (!p.endsWith(".md")) {
+    throw new KaddoMcpError("Work Item files must be markdown.");
+  }
+  const abs = path.resolve(root, p);
+  const base = toPosix(root).replace(/\/+$/, "");
+  if (toPosix(abs) !== base && !toPosix(abs).startsWith(base + "/")) {
+    throw new KaddoMcpError("Blocked unsafe work-item write path.");
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, "utf-8");
+}
+function removeWorkItemFile(root, relPath) {
+  const p = toPosix(relPath).replace(/^\/+/, "");
+  if (path.isAbsolute(relPath) || p.split("/").some((seg) => seg === "..")) {
+    throw new KaddoMcpError("Blocked unsafe work-item remove path.");
+  }
+  if (!p.startsWith("knowledge/delivery/work-items/")) {
+    throw new KaddoMcpError("Work Item removal can only target knowledge/delivery/work-items/.");
+  }
+  const abs = path.resolve(root, p);
+  if (fs.existsSync(abs)) fs.unlinkSync(abs);
+}
 function listFiles(root, relDir, filterExt) {
   let absDir;
   try {
@@ -382,7 +412,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) : [],
@@ -2419,6 +2449,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"),
@@ -2546,6 +2577,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",
@@ -2912,6 +2954,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
 
@@ -3301,9 +3345,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",
@@ -4316,7 +4360,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**.
@@ -6052,7 +6105,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;
 }
@@ -7680,7 +7734,14 @@ function optStr2(v) {
   return typeof v === "string" && v.trim() ? v.trim() : void 0;
 }
 function parseSource(data) {
-  const raw = data.source ? String(data.source) : "";
+  const rawSource = data.source;
+  if (rawSource != null && typeof rawSource === "object" && !Array.isArray(rawSource)) {
+    const obj = rawSource;
+    const t = optStr2(obj.type);
+    const type = t && VALID_SOURCES2.has(t) ? t : "unknown";
+    return { type, id: optStr2(obj.id) ?? optStr2(data.source_id), title: optStr2(obj.title) ?? optStr2(data.source_title), url: optStr2(obj.url) ?? optStr2(data.source_url), provider: optStr2(obj.provider) ?? optStr2(data.source_provider), inferred: obj.inferred === true || obj.inferred === "true" };
+  }
+  const raw = rawSource ? String(rawSource) : "";
   if (raw && VALID_SOURCES2.has(raw)) {
     return { type: raw, id: optStr2(data.source_id), title: optStr2(data.source_title), url: optStr2(data.source_url), provider: optStr2(data.source_provider), inferred: false };
   }
@@ -7721,23 +7782,53 @@ function listWorkItems(root) {
     }
     const data = parsed.data;
     if (!data.type) continue;
+    const status = lifecycleOf(data, rel);
+    const code = strArray(data.code);
+    const domains = strArray(data.domains);
+    const source = parseSource(data);
+    const readiness = status === "draft" ? assessReadiness(data, parsed.content, code, domains, source) : void 0;
     items.push({
       id: String(data.id ?? "") || rel,
       title: String(data.title ?? ""),
-      status: lifecycleOf(data, rel),
+      status,
       type: String(data.type ?? ""),
       knowledge_level: String(data.knowledge_level ?? ""),
       path: rel,
       summary: String(data.summary ?? "") || firstParagraph2(parsed.content),
-      code: strArray(data.code),
+      code,
       capabilities: strArray(data.capabilities),
       decisions: strArray(data.decisions),
       capsules: strArray(data.capsules),
-      source: parseSource(data)
+      source,
+      domains,
+      readiness
     });
   }
   return items.sort((a, b) => a.id.localeCompare(b.id));
 }
+function assessReadiness(data, content, code, domains, source) {
+  const body = content.trim();
+  const lower = body.toLowerCase();
+  const warnings = [];
+  if (domains.length === 0) warnings.push("No domains declared.");
+  if (code.length === 0) warnings.push("No code ownership globs declared.");
+  if (!/## acceptance criteria|## criterios de aceptación/i.test(body)) warnings.push("No acceptance criteria section found.");
+  if (!/## validation|## validación/i.test(body)) warnings.push("No validation section found.");
+  const oqMatch = body.match(/## (?:open questions|preguntas abiertas)\s*\n([\s\S]*?)(?=\n##|\n*$)/i);
+  if (oqMatch) {
+    const oqText = oqMatch[1].trim().toLowerCase();
+    if (oqText && !/^(none|ninguna|resolved|resueltas|deferred|diferidas)\.?$/i.test(oqText)) {
+      warnings.push("Open questions are still present.");
+    }
+  }
+  const hasRefinedBy = Boolean(data.refined_by);
+  const readyCandidate = hasRefinedBy && warnings.length === 0;
+  return {
+    readyCandidate,
+    warnings,
+    recommendedAction: readyCandidate ? "mark_work_item_ready" : void 0
+  };
+}
 
 // src/resources.ts
 function text(uri, body, mimeType = "text/markdown") {
@@ -8092,6 +8183,7 @@ function getPrompt(root, name) {
 }
 
 // src/tools.ts
+import matter10 from "gray-matter";
 var ok = (data) => ({ ok: true, data });
 var fail = (message) => ({ ok: false, message });
 function projectStatus(root) {
@@ -8137,6 +8229,62 @@ function getWorkItem(root, id) {
   const content = readText(root, item.path);
   return ok({ ...item, content: content ?? "" });
 }
+function markWorkItemReady(root, id, confirm) {
+  const item = listWorkItems(root).find((w) => w.id === id);
+  if (!item) return fail(`Work Item "${id}" not found.`);
+  if (item.status === "ready") {
+    return ok({ status: "already_ready", id: item.id, message: `Work Item ${item.id} is already ready.` });
+  }
+  if (item.status !== "draft") {
+    return fail(`Work Item ${item.id} is in state "${item.status}", not "draft". Only draft Work Items can be marked as ready.`);
+  }
+  const warnings = item.readiness?.warnings ?? [];
+  if (!confirm) {
+    return ok({
+      status: "needs_confirmation",
+      workItem: {
+        id: item.id,
+        title: item.title,
+        type: item.type,
+        status: item.status,
+        domains: item.domains,
+        source: item.source,
+        code: item.code,
+        readiness: item.readiness
+      },
+      command: `kaddo ready ${item.id}`,
+      message: `Review this Work Item and call mark_work_item_ready with confirm=true to mark it ready.`
+    });
+  }
+  const raw = readText(root, item.path);
+  if (!raw) return fail(`Could not read Work Item file: ${item.path}`);
+  const parsed = matter10(raw);
+  const data = { ...parsed.data };
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  data.status = "ready";
+  data.ready_at = today2;
+  const newContent = matter10.stringify(parsed.content, data);
+  const posixPath = item.path.replace(/\\/g, "/");
+  let newRelPath = item.path;
+  if (posixPath.includes("/work-items/draft/")) {
+    newRelPath = item.path.replace(/[/\\]draft[/\\]/, "/ready/");
+  }
+  writeWorkItemTransition(root, newRelPath, newContent);
+  if (newRelPath !== item.path) {
+    removeWorkItemFile(root, item.path);
+  }
+  const status = warnings.length > 0 ? "ready_with_warnings" : "ready";
+  return ok({
+    status,
+    id: item.id,
+    from: "draft",
+    to: "ready",
+    ready_at: today2,
+    moved: newRelPath !== item.path ? { from: item.path, to: newRelPath } : void 0,
+    ...warnings.length > 0 ? { warnings } : {},
+    next: ["Run kaddo context", "Run kaddo understand"]
+  });
+}
 function listCapsulesTool(root) {
   return ok(listCapsules(root));
 }
@@ -8178,7 +8326,7 @@ function listGraphHints(root, filter = {}) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter10 from "gray-matter";
+import matter11 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR3 = "knowledge";
 function readScanJson(dir) {
@@ -8191,7 +8339,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph3(markdown) {
-  const body = matter10(markdown).content.trim();
+  const body = matter11(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -9253,6 +9401,15 @@ function createServer(root) {
     { title: "Get Work Item", description: "Get a Work Item by ID (summary + full markdown).", inputSchema: { id: z2.string() } },
     async (args) => toolText(guarded(root, () => getWorkItem(root, args.id)))
   );
+  server.registerTool(
+    "kaddo_mark_work_item_ready",
+    {
+      title: "Mark Work Item ready",
+      description: "Assess whether a draft Work Item is ready for implementation. Without confirm, returns a preview with readiness warnings. With confirm=true, transitions the Work Item from draft to ready.",
+      inputSchema: { id: z2.string(), confirm: z2.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => markWorkItemReady(root, args.id, args.confirm)))
+  );
   server.registerTool(
     "kaddo_list_capsules",
     { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.56.0",
+  "version": "3.58.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {