@kaddo/mcp 3.96.0 → 3.97.0

package/dist/index.js

@@ -10285,6 +10285,18 @@ var RESOURCES = [
       return parts;
     }
   },
+  {
+    uri: "kaddo://build-contract",
+    name: "Kaddo build contract",
+    description: "The Kaddo-native Build Contract \u2014 lifecycle stages, entry/exit criteria, agents, skills, and CLI commands for the full Work Item lifecycle (Captured Intent \u2192 Completed).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://build-contract",
+      "knowledge/delivery/build-contract.md",
+      "Build Contract not found. Create knowledge/delivery/build-contract.md first."
+    )
+  },
   {
     uri: "kaddo://work-items",
     name: "Kaddo work items",
@@ -10533,8 +10545,11 @@ var EXTRA_INPUTS = {
   "graph-agent": [".kaddo/graph.json", ".kaddo/graph-hints.md"],
   "ownership-agent": ["knowledge/delivery/work-items/", "knowledge/inventory.md"],
   "capsule-agent": ["knowledge/product/capabilities.md", "knowledge/tech/decisions/"],
-  "work-item-agent": ["knowledge/delivery/roadmap.md"],
-  "implementation-agent": ["knowledge/tech/git-strategy.md"]
+  "work-item-agent": ["knowledge/delivery/roadmap.md", "knowledge/delivery/build-contract.md"],
+  "implementation-agent": ["knowledge/tech/git-strategy.md", "knowledge/delivery/build-contract.md", "knowledge/skills/implementation-planning/skill.md"],
+  "backlog-agent": ["knowledge/delivery/roadmap.md", "knowledge/delivery/work-items/"],
+  "architecture-agent": ["knowledge/tech/stack.md", "knowledge/tech/current-state.md", "knowledge/tech/decisions/"],
+  "module-context-agent": ["knowledge/tech/codebase.md", "knowledge/tech/current-state.md"]
 };
 function recommendedInputs(name) {
   return [".kaddo/context-pack.md", ...EXTRA_INPUTS[name] ?? []];
@@ -12426,6 +12441,93 @@ function agentGroupOf2(fileName) {
 function agentInstallPath2(fileName) {
   return `knowledge/agents/${agentGroupOf2(fileName)}/${fileName}`;
 }
+var CANDIDATES_DISCOVERY2 = "knowledge/tech/discovery/decision-candidates.md";
+var CANDIDATES_LEGACY2 = "knowledge/tech/decision-candidates.md";
+var DECISIONS_DIR2 = "knowledge/tech/decisions";
+function resolveCandidatesPath2(dir) {
+  const discovery = exists2(join3(dir, CANDIDATES_DISCOVERY2));
+  const legacy = exists2(join3(dir, CANDIDATES_LEGACY2));
+  if (discovery) return { path: CANDIDATES_DISCOVERY2, legacy: false, bothExist: legacy };
+  if (legacy) return { path: CANDIDATES_LEGACY2, legacy: true, bothExist: false };
+  return { path: null, legacy: false, bothExist: false };
+}
+function cleanCandidateTitle2(title) {
+  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
+}
+function slugify2(s) {
+  return cleanCandidateTitle2(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
+}
+function parseDecisionCandidates2(md) {
+  const out = [];
+  for (const line of md.split(/\r?\n/)) {
+    const m2 = line.match(/^##\s+(.+?)\s*$/);
+    if (m2) {
+      const raw = m2[1].trim();
+      if (!raw || /^_.*_$/.test(raw)) continue;
+      const t = cleanCandidateTitle2(raw);
+      if (t) out.push(t);
+    }
+  }
+  return out;
+}
+function countAdrs2(dir) {
+  const base = join3(dir, DECISIONS_DIR2);
+  if (!exists2(base)) return { total: 0, draft: 0, accepted: 0 };
+  let total = 0;
+  let draft = 0;
+  let accepted = 0;
+  for (const entry of readDir2(base)) {
+    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
+    const full = join3(base, entry);
+    if (!isFile2(full)) continue;
+    total += 1;
+    let content = "";
+    try {
+      content = readFile2(full);
+    } catch {
+      continue;
+    }
+    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
+    if (status === "accepted") accepted += 1;
+    else draft += 1;
+  }
+  return { total, draft, accepted };
+}
+function buildTechDecisions2(dir) {
+  const resolved = resolveCandidatesPath2(dir);
+  let titles = [];
+  if (resolved.path) {
+    try {
+      titles = parseDecisionCandidates2(readFile2(join3(dir, resolved.path)));
+    } catch {
+      titles = [];
+    }
+  }
+  const { total, draft, accepted } = countAdrs2(dir);
+  const candidate_list = titles.map((title, i) => {
+    const n = String(total + i + 1).padStart(3, "0");
+    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR2}/ADR-${n}-${slugify2(title)}.md` };
+  });
+  let status;
+  if (accepted > 0) status = "accepted-adrs";
+  else if (total > 0) status = "draft-adrs";
+  else if (titles.length > 0) status = "candidates";
+  else status = "none";
+  return {
+    status,
+    candidates: titles.length,
+    adrs: total,
+    draft_adrs: draft,
+    accepted_adrs: accepted,
+    candidate_list,
+    candidates_source: resolved.path,
+    candidates_legacy_location: resolved.legacy,
+    candidates_both_exist: resolved.bothExist
+  };
+}
+function hasUnmaterializedDecisions(td) {
+  return td.candidates > 0 && td.adrs === 0;
+}
 function resolveVersion2() {
   try {
     let dir = dirname2(fileURLToPath2(import.meta.url));
@@ -16360,7 +16462,7 @@ var WorkItemWriteError = class extends Error {
 function revisionOf(raw) {
   return crypto2.createHash("sha256").update(raw, "utf-8").digest("hex");
 }
-function slugify2(s) {
+function slugify22(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
 }
 function nextWorkItemId(dir) {
@@ -16506,7 +16608,7 @@ function createWorkItem(dir, opts) {
     relatedKnowledge: [],
     scopeConfidence: null
   });
-  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify2(title)}.md`;
+  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify22(title)}.md`;
   const filePath = join3(dir, relPath);
   if (exists2(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
   const raw = serialize(data, body);
@@ -16762,6 +16864,121 @@ function buildRefinementHandoff(dir, workItemId) {
     text: lines.join("\n")
   };
 }
+var WorkItemNotReadyError = class extends Error {
+  constructor(workItemId, actualState) {
+    super(`Work Item "${workItemId}" must be in "ready" state to produce an Implementation Handoff, but is "${actualState}".`);
+    this.workItemId = workItemId;
+    this.actualState = actualState;
+    this.name = "WorkItemNotReadyError";
+  }
+  workItemId;
+  actualState;
+};
+var RECOMMENDED_AGENT2 = "implementation-agent";
+var RECOMMENDED_SKILL2 = "implementation-planning";
+function buildImplementationHandoff(dir, workItemId) {
+  const artifacts = discoverWorkItems2(dir);
+  const match = artifacts.find((a2) => (a2.id || a2.title) === workItemId);
+  if (!match) throw new WorkItemNotFoundError(workItemId);
+  const lifecycle = lifecycleStateOf2({ status: match.status, filePath: match.filePath });
+  if (lifecycle !== "ready") throw new WorkItemNotReadyError(workItemId, lifecycle);
+  const config = loadConfig2(dir);
+  const projectName = config?.project.name ?? "this project";
+  const mappedModules = loadMappedModules2(dir).map((m2) => m2.id);
+  const multirepo = mappedModules.length > 0;
+  const techDecisions = buildTechDecisions2(dir);
+  const unmaterialized = hasUnmaterializedDecisions(techDecisions);
+  const wiId = match.id || match.title;
+  const wiTitle = match.title || match.id;
+  const affectedModules = match.affectedModules;
+  const domains = match.domains;
+  const scopeConfidence = match.scopeConfidence;
+  const lines = [
+    `Implement Work Item ${wiId} \u2014 "${wiTitle}" \u2014 in project "${projectName}" using Kaddo.`,
+    "",
+    `Use the canonical ${RECOMMENDED_AGENT2} and the ${RECOMMENDED_SKILL2} skill (via Kaddo MCP or skills),`,
+    "with access to this repository.",
+    "",
+    "--- Context Assembly ---",
+    "",
+    "Before planning, assemble context proportionally from these sources:",
+    "",
+    "1. Work Item: outcome, acceptance criteria, constraints, out-of-scope, affected modules, domains.",
+    "2. Knowledge: business, product, tech and delivery knowledge relevant to the Work Item domains.",
+    "3. System Context: topology, module dependencies, system graph when available.",
+    "4. Repository Context: existing patterns, file structure, test conventions in affected modules.",
+    "5. Related Work Items: dependencies (depends_on), completed related Work Items for precedent.",
+    "",
+    "Assemble proportionally: a single-module bugfix needs the affected module and its tests.",
+    "A cross-cutting feature needs topology, multiple modules, and business context.",
+    "",
+    "--- Design Deliberation ---",
+    "",
+    "Before writing code, document:",
+    "",
+    "- Technical Approach: how this will be implemented \u2014 patterns, modules, layers involved.",
+    "- Rationale: why this approach \u2014 reference existing patterns, constraints, or WI requirements.",
+    "- Alternatives Considered: when the change is non-trivial, document alternative approaches.",
+    "- Trade-offs: when alternatives exist, state what is gained and lost with the chosen approach.",
+    "",
+    "For trivial or obvious changes, Alternatives and Trade-offs may be omitted with a note explaining why."
+  ];
+  if (unmaterialized) {
+    lines.push(
+      "",
+      "--- ADR Recommendation ---",
+      "",
+      "This project has unmaterialized decision candidates. When the implementation involves an",
+      "architecturally significant decision, use the adr-writing skill to formalize it as an ADR",
+      "before implementing. Check knowledge/tech/discovery/decision-candidates.md for candidates."
+    );
+  }
+  if (multirepo) {
+    lines.push(
+      "",
+      `This is a multirepo project. Evaluate the scope across all relevant mapped modules (${mappedModules.join(", ")})`,
+      "before finalizing the implementation plan."
+    );
+  }
+  const topology = getSystemMapProjection(dir).metadata.topologyStatus;
+  if (topology !== "unavailable") {
+    lines.push(
+      "",
+      `The semantic system Graph is ${topology}. When semantic system topology is available:`,
+      "1. identify the relevant system entry points;",
+      "2. query the Kaddo Graph (search / neighbors / paths) for connected entities;",
+      "3. treat Graph results as impact candidates, not confirmed scope;",
+      "4. inspect the actual implementation in the repository for each candidate."
+    );
+  }
+  lines.push(
+    "",
+    "--- Implementation Plan ---",
+    "",
+    "Produce a plan with:",
+    "- Context Summary: what you assembled and consulted.",
+    "- Design Deliberation: Technical Approach, Rationale, and when relevant, Alternatives and Trade-offs.",
+    "- Affected Areas: modules, files, surfaces impacted.",
+    "- Implementation Steps: numbered steps with expected files per step.",
+    "- Validation Plan: how to verify \u2014 test commands, manual steps, AC verification.",
+    "- Stop Criteria: when to pause and ask \u2014 scope expansion, contradictions, missing knowledge.",
+    "",
+    "Do not start coding without explicit human confirmation of this plan."
+  );
+  return {
+    workItemId: wiId,
+    title: wiTitle,
+    projectName,
+    lifecycle,
+    affectedModules,
+    domains,
+    scopeConfidence,
+    hasUnmaterializedDecisions: unmaterialized,
+    recommendedAgent: RECOMMENDED_AGENT2,
+    recommendedSkill: RECOMMENDED_SKILL2,
+    text: lines.join("\n")
+  };
+}
 var WorkItemNotInProgressError = class extends Error {
   constructor(workItemId, actualState) {
     super(`Work Item "${workItemId}" must be in "in-progress" state for verification, but is "${actualState}".`);
@@ -18014,6 +18231,16 @@ function importWorkItemTool(root, args) {
     return fail("Work Item import failed.");
   }
 }
+function implementationHandoffTool(root, args) {
+  try {
+    const handoff = buildImplementationHandoff(root, args.workItemId);
+    return ok(handoff);
+  } catch (err) {
+    if (err instanceof WorkItemNotFoundError) return fail(err.message);
+    if (err instanceof WorkItemNotReadyError) return fail(err.message);
+    return fail("Implementation handoff failed.");
+  }
+}
 function collectEvidenceTool(root, args) {
   try {
     const result = collectImplementationEvidence(root, args.workItemId, args.evidence);
@@ -21596,6 +21823,17 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => importWorkItemTool(root, args)))
   );
+  server.registerTool(
+    "kaddo_implementation_handoff",
+    {
+      title: "Build Implementation Handoff",
+      description: 'Build an agent-agnostic Implementation Handoff for a ready Work Item. Assembles context guidance, design deliberation prompts, and implementation instructions. Returns structured handoff data including recommended agent, skill, affected modules, and copyable text. The Work Item must be in "ready" state. Does not start implementation \u2014 human confirmation is required first.',
+      inputSchema: {
+        workItemId: z4.string().describe("The Work Item ID (e.g. WI-005)")
+      }
+    },
+    async (args) => toolText(guarded(root, () => implementationHandoffTool(root, args)))
+  );
   const evidenceRepoSchema = z4.object({
     repoId: z4.string(),
     role: z4.string().optional(),

package/package.json

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