@kaddo/mcp 3.105.0 → 3.107.0

package/dist/index.js

@@ -10828,6 +10828,9 @@ function writeFile2(filePath, content) {
   fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
   fs3.writeFileSync(filePath, content, "utf-8");
 }
+function ensureDir2(dirPath) {
+  fs3.mkdirSync(dirPath, { recursive: true });
+}
 function readDir2(dirPath) {
   if (!exists2(dirPath)) return [];
   return fs3.readdirSync(dirPath);
@@ -11071,6 +11074,9 @@ function lifecycleStateOf2(item) {
   if (folder) return folder;
   return "ready";
 }
+function emptyLifecycleCounts2() {
+  return Object.fromEntries(LIFECYCLE_STATES2.map((s) => [s, 0]));
+}
 var ARCH_DIR3 = "knowledge";
 function toPosix6(p) {
   return p.replace(/\\/g, "/");
@@ -16967,7 +16973,7 @@ function createWorkItem(dir, opts) {
   if (!type) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${opts.type}".`);
   const id = nextWorkItemId(dir);
   const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
-  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today22 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
   const data = {
     type,
@@ -16975,7 +16981,7 @@ function createWorkItem(dir, opts) {
     title,
     status: "draft",
     work_type: type,
-    created_at: today2,
+    created_at: today22,
     source,
     generated_by: "kaddo-admin",
     affected_modules: [],
@@ -18581,6 +18587,7 @@ function getStatus(dir) {
     lastError: null
   };
 }
+var INITIATIVES_DIR = "knowledge/delivery/initiatives";
 var INITIATIVE_STATES = [
   "candidate",
   "planned",
@@ -18589,9 +18596,569 @@ var INITIATIVE_STATES = [
   "deferred",
   "cancelled"
 ];
+var INITIATIVE_TRANSITIONS = {
+  candidate: ["planned", "cancelled"],
+  planned: ["in-progress", "deferred", "cancelled"],
+  "in-progress": ["completed", "deferred", "cancelled"],
+  deferred: ["planned", "cancelled"],
+  completed: [],
+  cancelled: []
+};
 var STATUS_SET = new Set(INITIATIVE_STATES);
+function isValidInitiativeStatus(s) {
+  return STATUS_SET.has(s);
+}
+function isValidInitiativeTransition(from, to) {
+  return INITIATIVE_TRANSITIONS[from].includes(to);
+}
+function toPosix42(p) {
+  return p.replace(/\\/g, "/");
+}
+function optStr32(v) {
+  if (typeof v === "string" && v.trim()) return v.trim();
+  if (typeof v === "number") return String(v);
+  return void 0;
+}
+function strList2(v) {
+  if (!Array.isArray(v)) return [];
+  return v.map((x2) => typeof x2 === "string" ? x2.trim() : String(x2)).filter(Boolean);
+}
+function parseCandidates(data) {
+  const raw = data.candidates;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const o2 = entry;
+    const id = optStr32(o2.id);
+    const title = optStr32(o2.title);
+    if (!id || !title) continue;
+    out.push({
+      id,
+      title,
+      type: optStr32(o2.type),
+      suggestedKnowledgeLevel: optStr32(o2.suggested_knowledge_level ?? o2.knowledge_level),
+      expectedValue: optStr32(o2.expected_value),
+      notes: optStr32(o2.notes),
+      sourceSignals: strList2(o2.source_signals),
+      dependencies: strList2(o2.dependencies),
+      materializedAs: optStr32(o2.materialized_as) ?? null
+    });
+  }
+  return out;
+}
+function parseExternalLinks(data) {
+  const raw = data.external_links;
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const o2 = entry;
+    const integration = optStr32(o2.integration);
+    const externalId = optStr32(o2.external_id);
+    if (!integration || !externalId) continue;
+    out.push({
+      integration,
+      externalId,
+      externalType: optStr32(o2.external_type),
+      url: optStr32(o2.url)
+    });
+  }
+  return out;
+}
+function parseInitiative(dir, filePath, raw) {
+  let parsed;
+  try {
+    parsed = matter102(raw, {});
+  } catch {
+    return null;
+  }
+  const data = parsed.data;
+  if (optStr32(data.type) !== "initiative") return null;
+  const id = optStr32(data.id);
+  if (!id) return null;
+  const statusRaw = optStr32(data.status) ?? "planned";
+  const status = isValidInitiativeStatus(statusRaw) ? statusRaw : "planned";
+  return {
+    id,
+    title: optStr32(data.title) ?? id,
+    status,
+    horizon: optStr32(data.horizon) ?? null,
+    priority: optStr32(data.priority) ?? null,
+    knowledgeLevel: optStr32(data.knowledge_level) ?? null,
+    domains: strList2(data.domains),
+    relatedCapabilities: strList2(data.related_capabilities),
+    source: optStr32(data.source) ?? null,
+    sourceId: optStr32(data.source_id) ?? null,
+    createdAt: optStr32(data.created_at) ?? null,
+    externalLinks: parseExternalLinks(data),
+    candidates: parseCandidates(data),
+    filePath,
+    relPath: toPosix42(filePath).startsWith(toPosix42(dir) + "/") ? toPosix42(filePath).slice(toPosix42(dir).length + 1) : toPosix42(filePath),
+    body: parsed.content.trim(),
+    rawFrontmatter: data
+  };
+}
+function discoverInitiatives(dir) {
+  const iniDir = join3(dir, INITIATIVES_DIR);
+  if (!exists2(iniDir)) return [];
+  const out = [];
+  for (const entry of readDir2(iniDir)) {
+    if (!entry.endsWith(".md")) continue;
+    const full = join3(iniDir, entry);
+    if (!isFile2(full)) continue;
+    const ini = parseInitiative(dir, full, readFile2(full));
+    if (ini) out.push(ini);
+  }
+  return out.sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+function getInitiative(dir, id) {
+  const want = id.trim().toLowerCase();
+  return discoverInitiatives(dir).find((i) => i.id.toLowerCase() === want) ?? null;
+}
+function nextInitiativeId(dir) {
+  const iniDir = join3(dir, INITIATIVES_DIR);
+  let max = 0;
+  if (exists2(iniDir)) {
+    for (const entry of readDir2(iniDir)) {
+      const m2 = entry.match(/INI-(\d+)/);
+      if (m2) max = Math.max(max, parseInt(m2[1], 10));
+    }
+  }
+  return `INI-${String(max + 1).padStart(3, "0")}`;
+}
+function workItemBelongsToInitiative(workItemInitiative, iniId) {
+  const v = (workItemInitiative ?? "").trim().toLowerCase();
+  return v !== "" && v === iniId.trim().toLowerCase();
+}
+function associatedWorkItems(dir, iniId) {
+  return discoverWorkItems2(dir).filter((wi) => workItemBelongsToInitiative(wi.initiative, iniId)).map((wi) => ({
+    id: wi.id,
+    title: wi.title,
+    status: wi.lifecycle ?? "ready"
+  })).sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+function computeInitiativeProgress(dir, ini) {
+  const totalCandidates = ini.candidates.length;
+  const materialized = ini.candidates.filter((c) => c.materializedAs).length;
+  const byState = emptyLifecycleCounts2();
+  const associated = associatedWorkItems(dir, ini.id);
+  for (const wi of associated) byState[wi.status]++;
+  return {
+    initiative: ini.id,
+    status: ini.status,
+    planning: {
+      totalCandidates,
+      materialized,
+      remaining: Math.max(0, totalCandidates - materialized)
+    },
+    delivery: {
+      total: associated.length,
+      byState
+    }
+  };
+}
+function getInitiativeContext(dir, ini) {
+  return {
+    initiative: {
+      id: ini.id,
+      title: ini.title,
+      status: ini.status,
+      horizon: ini.horizon,
+      priority: ini.priority,
+      knowledgeLevel: ini.knowledgeLevel,
+      domains: ini.domains,
+      relatedCapabilities: ini.relatedCapabilities,
+      source: ini.source,
+      sourceId: ini.sourceId
+    },
+    progress: computeInitiativeProgress(dir, ini),
+    candidates: {
+      total: ini.candidates.length,
+      materialized: ini.candidates.filter((c) => c.materializedAs),
+      pending: ini.candidates.filter((c) => !c.materializedAs)
+    },
+    workItems: associatedWorkItems(dir, ini.id),
+    externalLinks: ini.externalLinks
+  };
+}
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 var DRAFT_DIR = `${WORK_ITEMS_DIR2}/draft`;
+var InitiativeWriteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitiativeWriteError";
+  }
+};
+function slugify3(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
+}
+function today2() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function candidateToData(c) {
+  const out = { id: c.id, title: c.title };
+  if (c.type) out.type = c.type;
+  if (c.suggestedKnowledgeLevel) out.suggested_knowledge_level = c.suggestedKnowledgeLevel;
+  if (c.expectedValue) out.expected_value = c.expectedValue;
+  if (c.notes) out.notes = c.notes;
+  if (c.sourceSignals.length) out.source_signals = c.sourceSignals;
+  if (c.dependencies.length) out.dependencies = c.dependencies;
+  if (c.materializedAs) out.materialized_as = c.materializedAs;
+  return out;
+}
+function externalLinkToData(l2) {
+  const out = { integration: l2.integration, external_id: l2.externalId };
+  if (l2.externalType) out.external_type = l2.externalType;
+  if (l2.url) out.url = l2.url;
+  return out;
+}
+function normalizeCandidate(input, fallbackId) {
+  return {
+    id: input.id?.trim() || fallbackId,
+    title: input.title.trim(),
+    type: input.type?.trim() || void 0,
+    suggestedKnowledgeLevel: input.suggestedKnowledgeLevel?.trim() || void 0,
+    expectedValue: input.expectedValue?.trim() || void 0,
+    notes: input.notes?.trim() || void 0,
+    sourceSignals: input.sourceSignals ?? [],
+    dependencies: input.dependencies ?? [],
+    materializedAs: input.materializedAs ?? null
+  };
+}
+function defaultBody(title) {
+  return [
+    `# ${title}`,
+    "",
+    "## Goal",
+    "",
+    "_What outcome does this Initiative pursue?_",
+    "",
+    "## Expected Value",
+    "",
+    "_Why it matters._",
+    "",
+    "## Scope",
+    "",
+    "_What this Initiative covers._",
+    "",
+    "## Out of Scope",
+    "",
+    "_What it explicitly does not cover._",
+    "",
+    "## Success Criteria",
+    "",
+    '_Observable outcomes that define completion (not just "all Work Items done")._',
+    "",
+    "## Dependencies",
+    "",
+    "_Other Initiatives, modules, or external work this depends on._",
+    "",
+    "## Work Item Candidates",
+    "",
+    "_Candidates live in frontmatter `candidates`; summarize them here as they evolve._",
+    "",
+    "## Open Questions",
+    "",
+    "_Unresolved questions for this Initiative._",
+    "",
+    "## Learning",
+    "",
+    "_Captured on completion: what was delivered, what stayed out of scope, outcome reached._",
+    ""
+  ].join("\n");
+}
+function buildInitiativeContent(id, input) {
+  const status = input.status ?? "planned";
+  if (!isValidInitiativeStatus(status)) {
+    throw new InitiativeWriteError(`Invalid initiative status: ${status}.`);
+  }
+  const candidates = (input.candidates ?? []).map(
+    (c, i) => normalizeCandidate(c, `WI-CANDIDATE-${String(i + 1).padStart(3, "0")}`)
+  );
+  const data = {
+    type: "initiative",
+    id,
+    title: input.title.trim(),
+    status,
+    knowledge_level: input.knowledgeLevel ?? "K2",
+    domains: input.domains ?? [],
+    related_capabilities: input.relatedCapabilities ?? [],
+    created_at: today2(),
+    external_links: (input.externalLinks ?? []).map(externalLinkToData),
+    candidates: candidates.map(candidateToData)
+  };
+  if (input.horizon) data.horizon = input.horizon;
+  if (input.priority) data.priority = input.priority;
+  if (input.source) data.source = input.source;
+  if (input.sourceId) data.source_id = input.sourceId;
+  return matter11.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
+}
+function createInitiative(dir, input) {
+  if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
+  const id = nextInitiativeId(dir);
+  const fileName = `${id}-${slugify3(input.title)}.md`;
+  const iniDir = join3(dir, INITIATIVES_DIR);
+  ensureDir2(iniDir);
+  const filePath = join3(iniDir, fileName);
+  const content = buildInitiativeContent(id, input);
+  writeFile2(filePath, content);
+  const ini = parseInitiative(dir, filePath, content);
+  if (!ini) throw new InitiativeWriteError("Failed to parse the Initiative just written.");
+  return ini;
+}
+function transitionInitiative(dir, id, to) {
+  const ini = getInitiative(dir, id);
+  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
+  if (!isValidInitiativeStatus(to)) throw new InitiativeWriteError(`Invalid status: ${to}.`);
+  if (ini.status === to) return ini;
+  if (!isValidInitiativeTransition(ini.status, to)) {
+    throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
+  }
+  const raw = readFile2(ini.filePath);
+  const { data, content } = matter11(raw, {});
+  data.status = to;
+  if (to === "completed") data.completed_at = today2();
+  const newContent = matter11.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
+  return updated;
+}
+function addCandidate(dir, id, candidate) {
+  const ini = getInitiative(dir, id);
+  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
+  const raw = readFile2(ini.filePath);
+  const { data, content } = matter11(raw, {});
+  const existing = Array.isArray(data.candidates) ? data.candidates : [];
+  const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
+  const normalized = normalizeCandidate(candidate, fallbackId);
+  if (ini.candidates.some((c) => c.id === normalized.id)) {
+    throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
+  }
+  data.candidates = [...existing, candidateToData(normalized)];
+  const newContent = matter11.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
+  return updated;
+}
+function updateInitiative(dir, id, patch) {
+  const ini = getInitiative(dir, id);
+  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
+  const raw = readFile2(ini.filePath);
+  const { data, content } = matter11(raw, {});
+  if (patch.title !== void 0) {
+    if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
+    data.title = patch.title.trim();
+  }
+  if (patch.horizon !== void 0) data.horizon = patch.horizon;
+  if (patch.priority !== void 0) data.priority = patch.priority;
+  if (patch.knowledgeLevel !== void 0) data.knowledge_level = patch.knowledgeLevel;
+  if (patch.domains !== void 0) data.domains = patch.domains;
+  if (patch.relatedCapabilities !== void 0) data.related_capabilities = patch.relatedCapabilities;
+  const newContent = matter11.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
+  return updated;
+}
+function nextWorkItemId2(dir) {
+  const wiDir = join3(dir, WORK_ITEMS_DIR2);
+  let max = 0;
+  const walk = (d3) => {
+    if (!exists2(d3)) return;
+    for (const entry of readDir2(d3)) {
+      const full = join3(d3, entry);
+      if (isFile2(full)) {
+        const m2 = entry.match(/WI-(\d+)/);
+        if (m2) max = Math.max(max, parseInt(m2[1], 10));
+      } else if (!entry.startsWith(".")) {
+        walk(full);
+      }
+    }
+  };
+  walk(wiDir);
+  return `WI-${String(max + 1).padStart(3, "0")}`;
+}
+function buildWorkItemContent(wiId, iniId, candidate) {
+  const data = {
+    type: candidate.type ?? "feature",
+    id: wiId,
+    title: candidate.title,
+    knowledge_level: candidate.suggestedKnowledgeLevel ?? "K2",
+    status: "draft",
+    phase: "now",
+    initiative: iniId,
+    domains: [],
+    code: [],
+    created_at: today2(),
+    source: "initiative",
+    source_id: candidate.id,
+    source_initiative: iniId,
+    affected_modules: []
+  };
+  if (candidate.sourceSignals.length) data.source_signals = candidate.sourceSignals;
+  if (candidate.dependencies.length) data.dependencies = candidate.dependencies;
+  const body = [
+    `# ${candidate.title}`,
+    "",
+    `> Materialized from Initiative ${iniId}, candidate ${candidate.id}.`,
+    "",
+    "## Problem",
+    "",
+    candidate.expectedValue ? `_Expected value:_ ${candidate.expectedValue}` : "_Describe the problem._",
+    "",
+    "## Acceptance Criteria",
+    "",
+    "- [ ] _Define at least one testable criterion._",
+    "",
+    "## Out of scope",
+    "",
+    "_Not included in this Work Item._",
+    "",
+    "## Validation",
+    "",
+    "_How will this be validated?_",
+    "",
+    "## Learning",
+    "",
+    "_What did we learn? Update after completion._",
+    ""
+  ].join("\n");
+  return matter11.stringify("\n" + body, data);
+}
+function materializeCandidate(dir, id, candidateId) {
+  const ini = getInitiative(dir, id);
+  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
+  const candidate = ini.candidates.find((c) => c.id === candidateId);
+  if (!candidate) throw new InitiativeWriteError(`Candidate ${candidateId} not found in ${id}.`);
+  if (candidate.materializedAs) {
+    throw new InitiativeWriteError(
+      `Candidate ${candidateId} is already materialized as ${candidate.materializedAs}.`
+    );
+  }
+  const wiId = nextWorkItemId2(dir);
+  const fileName = `${wiId}-${slugify3(candidate.title)}.md`;
+  ensureDir2(join3(dir, DRAFT_DIR));
+  writeFile2(join3(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
+  const raw = readFile2(ini.filePath);
+  const { data, content } = matter11(raw, {});
+  const cands = Array.isArray(data.candidates) ? data.candidates : [];
+  for (const c of cands) {
+    if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
+  }
+  data.candidates = cands;
+  const newContent = matter11.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
+  return { workItemId: wiId, fileName, initiative: updated };
+}
+var SUCCESS_HEADING_RE = /^#{1,6}\s*(success criteria|criterios de[ét]xito|criterios de éxito)\s*$/i;
+var HEADING_RE2 = /^#{1,6}\s+/;
+var CHECK_ITEM_RE = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/;
+var BULLET_RE2 = /^\s*[-*]\s+(.*)$/;
+var PLACEHOLDER_RE = /^_.*_$/;
+function parseSuccessCriteria(body) {
+  const lines = body.split(/\r?\n/);
+  const out = [];
+  let capture = false;
+  for (const line of lines) {
+    if (capture && HEADING_RE2.test(line)) break;
+    if (!capture) {
+      if (SUCCESS_HEADING_RE.test(line.trim())) capture = true;
+      continue;
+    }
+    const check = line.match(CHECK_ITEM_RE);
+    if (check) {
+      const text22 = check[2].trim();
+      if (text22 && !PLACEHOLDER_RE.test(text22)) {
+        out.push({ text: text22, checked: check[1].toLowerCase() === "x" });
+      }
+      continue;
+    }
+    const bullet = line.match(BULLET_RE2);
+    if (bullet) {
+      const text22 = bullet[1].trim();
+      if (text22 && !PLACEHOLDER_RE.test(text22)) out.push({ text: text22, checked: null });
+    }
+  }
+  return out;
+}
+function analyzeInitiative(dir, ini) {
+  const progress = computeInitiativeProgress(dir, ini);
+  const successCriteria = parseSuccessCriteria(ini.body);
+  const pendingCandidates = ini.candidates.filter((c) => !c.materializedAs);
+  const associated = associatedWorkItems(dir, ini.id);
+  const findings = [];
+  if (successCriteria.length === 0) {
+    findings.push({
+      code: "no-success-criteria",
+      severity: "warning",
+      message: "The Initiative has no explicit Success Criteria; completion cannot be judged by outcome, only by delivery."
+    });
+  } else {
+    const uncovered = successCriteria.filter((c) => c.checked === false);
+    if (uncovered.length > 0) {
+      findings.push({
+        code: "uncovered-success-criteria",
+        severity: "blocking",
+        message: `${uncovered.length} success criterion/criteria remain uncovered.`,
+        items: uncovered.map((c) => c.text)
+      });
+    }
+  }
+  if (pendingCandidates.length > 0) {
+    findings.push({
+      code: "pending-candidates",
+      severity: "blocking",
+      message: `${pendingCandidates.length} committed candidate(s) not yet materialized into Work Items.`,
+      items: pendingCandidates.map((c) => `${c.id}: ${c.title}`)
+    });
+  }
+  const notCompleted = associated.filter((w3) => w3.status !== "completed" && w3.status !== "archived");
+  if (associated.length === 0) {
+    findings.push({
+      code: "no-delivery",
+      severity: "info",
+      message: "No Work Items are associated with this Initiative yet."
+    });
+  } else if (notCompleted.length > 0) {
+    findings.push({
+      code: "incomplete-delivery",
+      severity: "blocking",
+      message: `${notCompleted.length} associated Work Item(s) are not completed.`,
+      items: notCompleted.map((w3) => `${w3.id} (${w3.status})`)
+    });
+  }
+  return {
+    initiative: ini.id,
+    status: ini.status,
+    progress,
+    successCriteria,
+    pendingCandidates,
+    findings,
+    suggestedCandidates: pendingCandidates
+  };
+}
+function evaluateInitiativeCompletion(dir, ini) {
+  const analysis = analyzeInitiative(dir, ini);
+  const reasons = [];
+  for (const f3 of analysis.findings) {
+    if (f3.severity === "blocking") reasons.push(f3.message);
+  }
+  if (analysis.progress.delivery.total === 0 && analysis.pendingCandidates.length === 0) {
+    reasons.push("Nothing has been delivered or committed under this Initiative.");
+  }
+  const ready = reasons.length === 0;
+  return {
+    initiative: ini.id,
+    ready,
+    readiness: ready ? "ready" : "not-ready",
+    reasons
+  };
+}
 
 // src/tools.ts
 var ok = (data) => ({ ok: true, data });
@@ -18690,9 +19257,9 @@ function markWorkItemReady(root, id, confirm2) {
   if (!raw) return fail(`Could not read Work Item file: ${item.path}`);
   const parsed = matter12(raw);
   const data = { ...parsed.data };
-  const today2 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
-  data.ready_at = today2;
+  data.ready_at = today3;
   const newContent = matter12.stringify(parsed.content, data);
   const posixPath = item.path.replace(/\\/g, "/");
   let newRelPath = item.path;
@@ -18709,7 +19276,7 @@ function markWorkItemReady(root, id, confirm2) {
     id: item.id,
     from: "draft",
     to: "ready",
-    ready_at: today2,
+    ready_at: today3,
     moved: newRelPath !== item.path ? { from: item.path, to: newRelPath } : void 0,
     ...warnings.length > 0 ? { warnings } : {},
     next: ["Run kaddo context", "Run kaddo understand"]
@@ -18932,7 +19499,7 @@ function firstParagraph3(md) {
   }
   return "";
 }
-function slugify3(s) {
+function slugify4(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
 }
 function modulesListTool(root, args) {
@@ -19119,7 +19686,7 @@ function extractSection(content, heading) {
   return out;
 }
 function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
-  const slug5 = slugify3(wi.title);
+  const slug5 = slugify4(wi.title);
   const wiLower = wi.id.toLowerCase();
   const coreBranch = `feature/${wiLower}-${slug5}`;
   const moduleBranches = {};
@@ -19182,7 +19749,7 @@ function exportCapsuleTool(root, args) {
       if (!mc) warnings.push("module-context.md not found for this module.");
       if (mc && isPlaceholder2(mc)) warnings.push("module-context.md contains placeholder sections.");
       capsuleType = "module";
-      capsuleName = `${slugify3(config.project?.name ?? "project")}-${args.module}`;
+      capsuleName = `${slugify4(config.project?.name ?? "project")}-${args.module}`;
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.project?.name ?? "unknown"}/${args.module}`,
@@ -19204,7 +19771,7 @@ function exportCapsuleTool(root, args) {
       if (mc && isPlaceholder2(mc)) warnings.push("module-context.md contains placeholder sections.");
       const modId = config.module?.id ?? args.module;
       capsuleType = "module";
-      capsuleName = slugify3(modId);
+      capsuleName = slugify4(modId);
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
@@ -19232,7 +19799,7 @@ function exportCapsuleTool(root, args) {
       responsibilities.push(mc ? `[${m2.id}] ${firstParagraph3(mc) || m2.name || m2.id}` : `[${m2.id}] ${m2.name || m2.id} (no module-context)`);
     }
     capsuleType = "system";
-    capsuleName = `${slugify3(config.project?.name ?? "project")}-system`;
+    capsuleName = `${slugify4(config.project?.name ?? "project")}-system`;
     capsuleData = {
       type: "knowledge-capsule",
       system: config.project?.name ?? "unknown",
@@ -19253,7 +19820,7 @@ function exportCapsuleTool(root, args) {
       if (mc && isPlaceholder2(mc)) warnings.push("module-context.md contains placeholder sections.");
       const modId = config.module?.id ?? "module";
       capsuleType = "module";
-      capsuleName = slugify3(modId);
+      capsuleName = slugify4(modId);
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
@@ -19269,7 +19836,7 @@ function exportCapsuleTool(root, args) {
       };
     } else {
       capsuleType = "project";
-      capsuleName = slugify3(config.project?.name ?? "project");
+      capsuleName = slugify4(config.project?.name ?? "project");
       capsuleData = {
         type: "knowledge-capsule",
         system: config.project?.name ?? "unknown",
@@ -19432,7 +19999,7 @@ var PROVENANCE2 = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewe
 function isRelative2(p) {
   return typeof p === "string" && p.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p) && !p.includes("..");
 }
-function strList2(v) {
+function strList3(v) {
   return Array.isArray(v) ? v.map((x2) => typeof x2 === "string" ? x2.trim() : "").filter(Boolean) : [];
 }
 function loadSystemTopology2(dir) {
@@ -19473,7 +20040,7 @@ function parseTopologyContent2(raw, dir) {
     const moduleRaw = typeof e.module === "string" ? e.module.trim() : void 0;
     if (moduleRaw && !validModules.has(moduleRaw)) findings.push({ level: "warning", message: `Entity "${id}" references unregistered module "${moduleRaw}".` });
     const rawImpl = e.implementation ?? e.implementation_refs;
-    const implementation = strList2(rawImpl).filter((p) => {
+    const implementation = strList3(rawImpl).filter((p) => {
       if (isRelative2(p)) return true;
       findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p}" is not a safe relative path and was dropped.` });
       return false;
@@ -19481,7 +20048,7 @@ function parseTopologyContent2(raw, dir) {
     const prov = e.provenance;
     const provOrigin = typeof prov === "string" ? prov : prov && typeof prov === "object" && typeof prov.origin === "string" ? String(prov.origin) : void 0;
     const provenance = provOrigin && PROVENANCE2.has(provOrigin) ? provOrigin : void 0;
-    const evidence = strList2(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative2);
+    const evidence = strList3(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative2);
     seenIds.add(id);
     entities.push({
       id,
@@ -19490,7 +20057,7 @@ function parseTopologyContent2(raw, dir) {
       ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
       ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
       implementationRefs: implementation,
-      knowledgeRefs: strList2(e.knowledge ?? e.knowledge_refs),
+      knowledgeRefs: strList3(e.knowledge ?? e.knowledge_refs),
       ...provenance ? { provenance } : {},
       evidence
     });
@@ -19524,7 +20091,7 @@ function parseTopologyContent2(raw, dir) {
     }
     seenRels.add(key);
     const prov = r2.provenance;
-    relationships.push({ from, to, type, evidence: strList2(r2.evidence ?? prov?.evidence_refs).filter(isRelative2) });
+    relationships.push({ from, to, type, evidence: strList3(r2.evidence ?? prov?.evidence_refs).filter(isRelative2) });
   }
   return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
 }
@@ -22094,6 +22661,147 @@ function generateCapsuleDraft(root) {
   };
 }
 
+// src/initiatives.ts
+var ok5 = (data) => ({ ok: true, data });
+var fail4 = (message) => ({ ok: false, message });
+function listInitiativesTool(root) {
+  const all = discoverInitiatives(root).map((ini) => {
+    const p = computeInitiativeProgress(root, ini);
+    return {
+      id: ini.id,
+      title: ini.title,
+      status: ini.status,
+      planning: p.planning,
+      delivery: p.delivery
+    };
+  });
+  return ok5(all);
+}
+function getInitiativeTool(root, id) {
+  const ini = getInitiative(root, id);
+  if (!ini) return fail4(`Initiative ${id} not found.`);
+  return ok5({
+    id: ini.id,
+    title: ini.title,
+    status: ini.status,
+    horizon: ini.horizon,
+    priority: ini.priority,
+    knowledgeLevel: ini.knowledgeLevel,
+    domains: ini.domains,
+    relatedCapabilities: ini.relatedCapabilities,
+    source: ini.source,
+    sourceId: ini.sourceId,
+    externalLinks: ini.externalLinks,
+    candidates: ini.candidates,
+    body: ini.body
+  });
+}
+function getInitiativeContextTool(root, id) {
+  const ini = getInitiative(root, id);
+  if (!ini) return fail4(`Initiative ${id} not found.`);
+  return ok5(getInitiativeContext(root, ini));
+}
+function getInitiativeProgressTool(root, id) {
+  const ini = getInitiative(root, id);
+  if (!ini) return fail4(`Initiative ${id} not found.`);
+  return ok5(computeInitiativeProgress(root, ini));
+}
+function previewOrApply(confirm2, action, effect, apply) {
+  if (!confirm2) {
+    return ok5({ action, effect, instruction: "Call again with confirm=true to apply." });
+  }
+  try {
+    return ok5({ applied: true, result: apply() });
+  } catch (err) {
+    if (err instanceof InitiativeWriteError) return fail4(err.message);
+    throw err;
+  }
+}
+function createInitiativeTool(root, args) {
+  if (!args.title?.trim()) return fail4("title is required.");
+  return previewOrApply(
+    args.confirm,
+    "create-initiative",
+    `A new Initiative "${args.title.trim()}" will be created under knowledge/delivery/initiatives/.`,
+    () => createInitiative(root, {
+      title: args.title,
+      domains: args.domains,
+      relatedCapabilities: args.relatedCapabilities,
+      horizon: args.horizon,
+      priority: args.priority
+    })
+  );
+}
+function updateInitiativeTool(root, args) {
+  if (!getInitiative(root, args.id)) return fail4(`Initiative ${args.id} not found.`);
+  const changingStatus = typeof args.status === "string";
+  const effect = changingStatus ? `Initiative ${args.id} status will transition to "${args.status}" (valid transitions only).` : `Initiative ${args.id} fields will be updated.`;
+  return previewOrApply(args.confirm, "update-initiative", effect, () => {
+    if (changingStatus) {
+      return transitionInitiative(root, args.id, args.status);
+    }
+    return updateInitiative(root, args.id, {
+      title: args.title,
+      horizon: args.horizon,
+      priority: args.priority,
+      domains: args.domains,
+      relatedCapabilities: args.relatedCapabilities
+    });
+  });
+}
+function addInitiativeCandidateTool(root, args) {
+  if (!args.title?.trim()) return fail4("candidate title is required.");
+  if (!getInitiative(root, args.id)) return fail4(`Initiative ${args.id} not found.`);
+  return previewOrApply(
+    args.confirm,
+    "add-initiative-candidate",
+    `A Work Item candidate "${args.title.trim()}" will be added to ${args.id}.`,
+    () => addCandidate(root, args.id, {
+      title: args.title,
+      type: args.type,
+      suggestedKnowledgeLevel: args.suggestedKnowledgeLevel,
+      expectedValue: args.expectedValue,
+      notes: args.notes
+    })
+  );
+}
+function materializeInitiativeCandidateTool(root, args) {
+  const ini = getInitiative(root, args.id);
+  if (!ini) return fail4(`Initiative ${args.id} not found.`);
+  const candidate = ini.candidates.find((c) => c.id === args.candidateId);
+  if (!candidate) return fail4(`Candidate ${args.candidateId} not found in ${args.id}.`);
+  return previewOrApply(
+    args.confirm,
+    "materialize-initiative-candidate",
+    `Candidate ${args.candidateId} ("${candidate.title}") will be materialized into a draft Work Item associated to ${args.id}.`,
+    () => materializeCandidate(root, args.id, args.candidateId)
+  );
+}
+function analyzeInitiativeTool(root, id) {
+  const ini = getInitiative(root, id);
+  if (!ini) return fail4(`Initiative ${id} not found.`);
+  return ok5(analyzeInitiative(root, ini));
+}
+function completeInitiativeTool(root, args) {
+  const ini = getInitiative(root, args.id);
+  if (!ini) return fail4(`Initiative ${args.id} not found.`);
+  const readiness = evaluateInitiativeCompletion(root, ini);
+  if (!args.confirm) {
+    return ok5({
+      action: "complete-initiative",
+      readiness,
+      instruction: readiness.ready ? "Initiative looks ready. Call again with confirm=true to complete (human decision)." : "Initiative is NOT ready (see readiness.reasons). Completion requires an explicit human decision: call again with confirm=true only if the human chooses to complete anyway."
+    });
+  }
+  try {
+    const done = transitionInitiative(root, args.id, "completed");
+    return ok5({ applied: true, readiness, result: { id: done.id, status: done.status } });
+  } catch (err) {
+    if (err instanceof InitiativeWriteError) return fail4(err.message);
+    throw err;
+  }
+}
+
 // src/server.ts
 var SERVER_NAME = "kaddo";
 var require2 = createRequire(import.meta.url);
@@ -22490,6 +23198,110 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => verifyWorkItemTool(root, args)))
   );
+  const INITIATIVE_READ_NOTE = "Read-only. Initiatives are an optional outcome/traceability layer over Work Items; a Work Item never requires one.";
+  server.registerTool(
+    "kaddo_list_initiatives",
+    { title: "List initiatives", description: `List initiatives with planning coverage and delivery progress. ${INITIATIVE_READ_NOTE}`, inputSchema: {} },
+    async () => toolText(guarded(root, () => listInitiativesTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_initiative",
+    { title: "Get initiative", description: `Get one initiative: metadata, candidates and body. ${INITIATIVE_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getInitiativeTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_get_initiative_context",
+    {
+      title: "Get initiative context",
+      description: `Focused, initiative-scoped context for analysis: the initiative, progress, candidates (materialized/pending), associated Work Items and external links. Does NOT load the whole project. ${INITIATIVE_READ_NOTE}`,
+      inputSchema: { id: z4.string() }
+    },
+    async (args) => toolText(guarded(root, () => getInitiativeContextTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_get_initiative_progress",
+    { title: "Get initiative progress", description: `Planning coverage (candidates materialized/total) and delivery progress (Work Items by lifecycle state). ${INITIATIVE_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getInitiativeProgressTool(root, args.id)))
+  );
+  const INITIATIVE_WRITE_NOTE = "Without confirm=true returns a preview. With confirm=true applies the change. Writes only under knowledge/delivery/.";
+  server.registerTool(
+    "kaddo_create_initiative",
+    {
+      title: "Create initiative",
+      description: `Create a new initiative. ${INITIATIVE_WRITE_NOTE}`,
+      inputSchema: {
+        title: z4.string(),
+        domains: z4.array(z4.string()).optional(),
+        relatedCapabilities: z4.array(z4.string()).optional(),
+        horizon: z4.string().optional(),
+        priority: z4.string().optional(),
+        confirm: z4.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => createInitiativeTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_update_initiative",
+    {
+      title: "Update initiative",
+      description: `Update an initiative's status (valid lifecycle transitions only) or non-lifecycle fields. ${INITIATIVE_WRITE_NOTE}`,
+      inputSchema: {
+        id: z4.string(),
+        status: z4.enum(["planned", "in-progress", "completed", "deferred", "cancelled"]).optional(),
+        title: z4.string().optional(),
+        horizon: z4.string().optional(),
+        priority: z4.string().optional(),
+        domains: z4.array(z4.string()).optional(),
+        relatedCapabilities: z4.array(z4.string()).optional(),
+        confirm: z4.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => updateInitiativeTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_add_initiative_candidate",
+    {
+      title: "Add initiative candidate",
+      description: `Add a Work Item candidate to an initiative (not yet materialized). ${INITIATIVE_WRITE_NOTE}`,
+      inputSchema: {
+        id: z4.string(),
+        title: z4.string(),
+        type: z4.string().optional(),
+        suggestedKnowledgeLevel: z4.string().optional(),
+        expectedValue: z4.string().optional(),
+        notes: z4.string().optional(),
+        confirm: z4.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => addInitiativeCandidateTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_materialize_initiative_candidate",
+    {
+      title: "Materialize initiative candidate",
+      description: `Materialize an initiative candidate into a draft Work Item associated via \`initiative: INI-xxx\`. ${INITIATIVE_WRITE_NOTE}`,
+      inputSchema: { id: z4.string(), candidateId: z4.string(), confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => materializeInitiativeCandidateTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_analyze_initiative",
+    {
+      title: "Analyze initiative",
+      description: `Read-only gap analysis: success-criteria coverage, pending candidates, delivery status, grounded findings, and the Initiative's own pending candidates as suggestions. Never invents work. ${INITIATIVE_READ_NOTE}`,
+      inputSchema: { id: z4.string() }
+    },
+    async (args) => toolText(guarded(root, () => analyzeInitiativeTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_complete_initiative",
+    {
+      title: "Complete initiative",
+      description: "Human-gated completion. Without confirm returns completion readiness (does NOT complete). With confirm=true transitions the Initiative to completed; readiness findings are returned either way so uncovered scope stays visible. Never completes autonomously.",
+      inputSchema: { id: z4.string(), confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => completeInitiativeTool(root, args)))
+  );
   server.registerTool(
     "kaddo_telemetry_status",
     {

package/package.json

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