@kaddo/mcp 3.130.0 → 3.131.0

package/dist/index.js

@@ -391,7 +391,7 @@ function join(...parts) {
 }
 
 // ../cli/src/core/impact-report.ts
-import matter12 from "gray-matter";
+import matter13 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
@@ -2599,6 +2599,9 @@ function parseInitiative(dir, filePath, raw) {
     source: optStr(data.source) ?? null,
     sourceId: optStr(data.source_id) ?? null,
     createdAt: optStr(data.created_at) ?? null,
+    epic: optStr(data.epic) ?? null,
+    owners: strList(data.owners),
+    contributors: strList(data.contributors),
     externalLinks: parseExternalLinks(data),
     candidates: parseCandidates(data),
     filePath,
@@ -2621,8 +2624,123 @@ function discoverInitiatives(dir) {
   return out.sort((a2, b2) => a2.id.localeCompare(b2.id));
 }
 
-// ../cli/src/core/resources.ts
+// ../cli/src/core/delivery-planning.ts
 import matter6 from "gray-matter";
+var DELIVERY_PLANS_DIR = "knowledge/delivery/plans";
+var EPICS_DIR = "knowledge/delivery/epics";
+var PLAN_STATES = ["draft", "in-progress", "completed", "cancelled"];
+var EPIC_STATES = ["planned", "in-progress", "completed", "cancelled"];
+function toPosix4(p) {
+  return p.replace(/\\/g, "/");
+}
+function optStr2(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 relFrom(dir, filePath) {
+  const d3 = toPosix4(dir);
+  const f3 = toPosix4(filePath);
+  return f3.startsWith(d3 + "/") ? f3.slice(d3.length + 1) : f3;
+}
+function parseMilestones(data) {
+  const raw = data.milestones;
+  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 = optStr2(o2.id);
+    if (!id) continue;
+    out.push({ id, title: optStr2(o2.title) ?? id, exitCriteria: strList2(o2.exit_criteria) });
+  }
+  return out;
+}
+function parseDeliveryPlan(dir, filePath, raw) {
+  let parsed;
+  try {
+    parsed = matter6(raw, {});
+  } catch {
+    return null;
+  }
+  const data = parsed.data;
+  if (optStr2(data.type) !== "delivery-plan") return null;
+  const id = optStr2(data.id);
+  if (!id) return null;
+  const statusRaw = optStr2(data.status) ?? "draft";
+  const status = PLAN_STATES.includes(statusRaw) ? statusRaw : "draft";
+  return {
+    id,
+    title: optStr2(data.title) ?? id,
+    status,
+    objective: optStr2(data.objective) ?? null,
+    milestones: parseMilestones(data),
+    dependsOn: strList2(data.depends_on),
+    successCriteria: strList2(data.success_criteria),
+    risks: strList2(data.risks),
+    references: strList2(data.references),
+    filePath,
+    relPath: relFrom(dir, filePath),
+    body: parsed.content.trim(),
+    rawFrontmatter: data
+  };
+}
+function parseEpic(dir, filePath, raw) {
+  let parsed;
+  try {
+    parsed = matter6(raw, {});
+  } catch {
+    return null;
+  }
+  const data = parsed.data;
+  if (optStr2(data.type) !== "epic") return null;
+  const id = optStr2(data.id);
+  if (!id) return null;
+  const statusRaw = optStr2(data.status) ?? "planned";
+  const status = EPIC_STATES.includes(statusRaw) ? statusRaw : "planned";
+  return {
+    id,
+    title: optStr2(data.title) ?? id,
+    status,
+    outcome: optStr2(data.outcome ?? data.expected_outcome) ?? null,
+    plan: optStr2(data.plan) ?? null,
+    milestone: optStr2(data.milestone) ?? null,
+    dependsOn: strList2(data.depends_on),
+    successCriteria: strList2(data.success_criteria),
+    relatedCapabilities: strList2(data.related_capabilities),
+    decisions: strList2(data.decisions),
+    filePath,
+    relPath: relFrom(dir, filePath),
+    body: parsed.content.trim(),
+    rawFrontmatter: data
+  };
+}
+function discoverIn(dir, rel, parse3) {
+  const d3 = join(dir, rel);
+  if (!exists(d3)) return [];
+  const out = [];
+  for (const entry of readDir(d3)) {
+    if (!entry.endsWith(".md")) continue;
+    const full = join(d3, entry);
+    if (!isFile(full)) continue;
+    const parsed = parse3(dir, full, readFile(full));
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+function discoverDeliveryPlans(dir) {
+  return discoverIn(dir, DELIVERY_PLANS_DIR, parseDeliveryPlan).sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+function discoverEpics(dir) {
+  return discoverIn(dir, EPICS_DIR, parseEpic).sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+
+// ../cli/src/core/resources.ts
+import matter7 from "gray-matter";
 var RESOURCE_ARTIFACT_TYPE = "project-resource";
 var RESOURCE_TYPES = [
   "database",
@@ -2738,7 +2856,7 @@ function purposeFromBody(body) {
   return text3 || null;
 }
 function toDetail(filePath, relPath, raw) {
-  const parsed = matter6(raw);
+  const parsed = matter7(raw);
   const fm = parsed.data ?? {};
   const body = parsed.content.trim();
   const id = str(fm.id) ?? "";
@@ -2800,7 +2918,7 @@ function parseWorkItemResources(fm) {
 }
 
 // ../cli/src/core/deprecation.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 var DEPRECATION_ARTIFACT_TYPE = "deprecation-plan";
 var DEPRECATION_PLANS_DIR = "knowledge/legacy/deprecations";
 var TARGET_TYPES = [
@@ -2991,7 +3109,7 @@ function getDeprecationPlan(dir, id) {
   );
   if (!match) return null;
   const raw = readFile(match.filePath);
-  const parsed = matter7(raw);
+  const parsed = matter8(raw);
   const fm = parsed.data ?? {};
   const body = parsed.content.trim();
   const targets = parseTargets(fm.targets);
@@ -3058,14 +3176,14 @@ var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
 function scopeStatuses(scope) {
   return scope === "all" ? { included: ALL_STATUSES, excluded: ["archived"] } : { included: ACTIVE_STATUSES, excluded: ["completed", "archived"] };
 }
-function toPosix4(p) {
+function toPosix5(p) {
   return p.replace(/\\/g, "/");
 }
 function slug(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr(a2) {
-  return toPosix4(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
+  return toPosix5(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
 }
 function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   const scope = opts.scope ?? "active";
@@ -3176,6 +3294,27 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
   }
+  for (const plan of discoverDeliveryPlans(dir)) {
+    const planId = `delivery-plan:${slug(plan.id) || plan.id}`;
+    addNode({ id: planId, type: "delivery-plan", label: `${plan.id} ${plan.title}`.trim(), path: plan.relPath, status: plan.status });
+    for (const m2 of plan.milestones) {
+      const milestoneId = `milestone:${slug(plan.id)}:${slug(m2.id) || m2.id}`;
+      addNode({ id: milestoneId, type: "milestone", label: `${m2.id} ${m2.title}`.trim(), path: plan.relPath });
+      addEdge(milestoneId, planId, "belongs_to");
+    }
+  }
+  for (const epic of discoverEpics(dir)) {
+    const epicNodeId = `epic:${slug(epic.id) || epic.id}`;
+    addNode({ id: epicNodeId, type: "epic", label: `${epic.id} ${epic.title}`.trim(), path: epic.relPath, status: epic.status });
+    if (epic.plan) {
+      addEdge(epicNodeId, `delivery-plan:${slug(epic.plan)}`, "belongs_to");
+      if (epic.milestone) addEdge(epicNodeId, `milestone:${slug(epic.plan)}:${slug(epic.milestone)}`, "belongs_to");
+    }
+    for (const dep of epic.dependsOn) addEdge(epicNodeId, `epic:${slug(dep)}`, "depends_on");
+  }
+  for (const ini of discoverInitiatives(dir)) {
+    if (ini.epic) addEdge(`initiative:${slug(ini.id) || ini.id}`, `epic:${slug(ini.epic)}`, "belongs_to");
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -3347,14 +3486,14 @@ function loadGraphSummary(dir) {
 
 // ../cli/src/core/graph-hints.ts
 var KNOWLEDGE4 = "knowledge";
-function toPosix5(p) {
+function toPosix6(p) {
   return p.replace(/\\/g, "/");
 }
 function slug2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr2(a2) {
-  return toPosix5(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
+  return toPosix6(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
 }
 function capabilityHeadings(dir) {
   const p = join(dir, KNOWLEDGE4, "product", "capabilities.md");
@@ -3589,7 +3728,7 @@ function loadGraphHints(dir) {
 }
 
 // ../cli/src/services/installed-skills.ts
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 var SKILLS_DIR = join("knowledge", "skills");
 function discoverInstalledSkills(dir) {
   const base = join(dir, SKILLS_DIR);
@@ -3599,7 +3738,7 @@ function discoverInstalledSkills(dir) {
     const skillFile = join(base, entry, "skill.md");
     if (!isFile(skillFile)) continue;
     try {
-      const { data } = matter8(readFile(skillFile));
+      const { data } = matter9(readFile(skillFile));
       if (data.type && String(data.type) !== "skill") continue;
       const id = String(data.id ?? entry);
       out.push({
@@ -4705,7 +4844,7 @@ function readPocSummary(dir) {
 
 // ../cli/src/core/poc-report.ts
 import { createHash } from "crypto";
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 var POC_REPORT_PREFIX = "poc-report-v";
 var SECRET_LINE = /(^|\s)(?:[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)|(?:token|secret|password|api[_-]?key))\s*[:=]\s*\S+/i;
 var reportName = /^poc-report-v(\d{3,})\.md$/;
@@ -4733,7 +4872,7 @@ function reportFiles(dir) {
     const match = name.match(reportName);
     if (!match) return [];
     try {
-      const parsed = matter9(readFile(join(delivery, name)));
+      const parsed = matter10(readFile(join(delivery, name)));
       const fingerprint = typeof parsed.data.source_fingerprint === "string" ? parsed.data.source_fingerprint : "";
       const manifest = parsed.data.source_manifest;
       const sourceManifest = manifest && typeof manifest === "object" && !Array.isArray(manifest) ? Object.fromEntries(Object.entries(manifest).filter(([, digest]) => typeof digest === "string")) : {};
@@ -5379,7 +5518,7 @@ function deriveDeliveryCompletedStatus(dir) {
 }
 
 // ../cli/src/core/assets.ts
-import matter10 from "gray-matter";
+import matter11 from "gray-matter";
 
 // ../cli/src/core/version.ts
 import { fileURLToPath } from "url";
@@ -6343,9 +6482,9 @@ var RESPONSIBILITY_MATRIX = {
   },
   "roadmap-agent": {
     agent: "roadmap-agent",
-    responsibleFor: ["Roadmap", "Initiatives", "Work Item candidates"],
+    responsibleFor: ["Roadmap", "Initiatives", "Work Item candidates", "Delivery Plans and Epics (optional planning layer)"],
     produces: ["knowledge/delivery/roadmap.md"],
-    canSuggest: ["kaddo create --from roadmap", "work-item-agent"],
+    canSuggest: ["kaddo create --from roadmap", "work-item-agent", "kaddo plan create", "kaddo epic create"],
     cannotSuggest: ["branches", "commits", "pull requests", "code"],
     next: ["kaddo create --from roadmap", "work-item-agent"]
   },
@@ -8846,7 +8985,7 @@ function canonicalSkills() {
 }
 function versionOf(content) {
   try {
-    const v = matter10(content).data.version;
+    const v = matter11(content).data.version;
     return v === void 0 || v === null ? null : String(v);
   } catch {
     return null;
@@ -9038,19 +9177,19 @@ function parseWorkItemSource(frontmatter) {
   const rawSource = frontmatter.source;
   if (rawSource != null && typeof rawSource === "object" && !Array.isArray(rawSource)) {
     const obj = rawSource;
-    const t = optStr2(obj.type);
+    const t = optStr3(obj.type);
     const type = t && isValidSource(t) ? t : "unknown";
     return {
       type,
-      id: optStr2(obj.id) ?? optStr2(frontmatter.source_id),
-      title: optStr2(obj.title) ?? optStr2(frontmatter.source_title),
-      context: optStr2(obj.context) ?? optStr2(frontmatter.source_context),
-      provider: optStr2(obj.provider) ?? optStr2(frontmatter.source_provider),
-      integration: optStr2(obj.integration) ?? optStr2(frontmatter.source_integration),
-      url: optStr2(obj.url) ?? optStr2(frontmatter.source_url),
-      imported_at: optStr2(obj.imported_at) ?? optStr2(frontmatter.source_imported_at),
-      external_updated_at: optStr2(obj.external_updated_at) ?? optStr2(frontmatter.source_external_updated_at),
-      synced_at: optStr2(obj.synced_at) ?? optStr2(frontmatter.source_synced_at),
+      id: optStr3(obj.id) ?? optStr3(frontmatter.source_id),
+      title: optStr3(obj.title) ?? optStr3(frontmatter.source_title),
+      context: optStr3(obj.context) ?? optStr3(frontmatter.source_context),
+      provider: optStr3(obj.provider) ?? optStr3(frontmatter.source_provider),
+      integration: optStr3(obj.integration) ?? optStr3(frontmatter.source_integration),
+      url: optStr3(obj.url) ?? optStr3(frontmatter.source_url),
+      imported_at: optStr3(obj.imported_at) ?? optStr3(frontmatter.source_imported_at),
+      external_updated_at: optStr3(obj.external_updated_at) ?? optStr3(frontmatter.source_external_updated_at),
+      synced_at: optStr3(obj.synced_at) ?? optStr3(frontmatter.source_synced_at),
       inferred: obj.inferred === true || obj.inferred === "true",
       reason: t && !isValidSource(t) ? `Invalid source type in object: "${t}".` : void 0
     };
@@ -9059,28 +9198,28 @@ function parseWorkItemSource(frontmatter) {
   if (raw && isValidSource(raw)) {
     return {
       type: raw,
-      id: optStr2(frontmatter.source_id),
-      title: optStr2(frontmatter.source_title),
-      context: optStr2(frontmatter.source_context),
-      provider: optStr2(frontmatter.source_provider),
-      url: optStr2(frontmatter.source_url),
-      imported_at: optStr2(frontmatter.source_imported_at),
-      external_updated_at: optStr2(frontmatter.source_external_updated_at),
-      synced_at: optStr2(frontmatter.source_synced_at),
+      id: optStr3(frontmatter.source_id),
+      title: optStr3(frontmatter.source_title),
+      context: optStr3(frontmatter.source_context),
+      provider: optStr3(frontmatter.source_provider),
+      url: optStr3(frontmatter.source_url),
+      imported_at: optStr3(frontmatter.source_imported_at),
+      external_updated_at: optStr3(frontmatter.source_external_updated_at),
+      synced_at: optStr3(frontmatter.source_synced_at),
       inferred: false
     };
   }
   if (raw && !isValidSource(raw)) {
     return {
       type: "unknown",
-      id: optStr2(frontmatter.source_id),
-      title: optStr2(frontmatter.source_title),
-      context: optStr2(frontmatter.source_context),
-      provider: optStr2(frontmatter.source_provider),
-      url: optStr2(frontmatter.source_url),
-      imported_at: optStr2(frontmatter.source_imported_at),
-      external_updated_at: optStr2(frontmatter.source_external_updated_at),
-      synced_at: optStr2(frontmatter.source_synced_at),
+      id: optStr3(frontmatter.source_id),
+      title: optStr3(frontmatter.source_title),
+      context: optStr3(frontmatter.source_context),
+      provider: optStr3(frontmatter.source_provider),
+      url: optStr3(frontmatter.source_url),
+      imported_at: optStr3(frontmatter.source_imported_at),
+      external_updated_at: optStr3(frontmatter.source_external_updated_at),
+      synced_at: optStr3(frontmatter.source_synced_at),
       inferred: true,
       reason: `Invalid source value: "${raw}".`
     };
@@ -9088,8 +9227,8 @@ function parseWorkItemSource(frontmatter) {
   if (frontmatter.source_work_item_candidate || frontmatter.source_roadmap_initiative) {
     return {
       type: "roadmap",
-      id: optStr2(frontmatter.source_id) ?? optStr2(frontmatter.source_work_item_candidate),
-      title: optStr2(frontmatter.source_initiative_title),
+      id: optStr3(frontmatter.source_id) ?? optStr3(frontmatter.source_work_item_candidate),
+      title: optStr3(frontmatter.source_initiative_title),
       inferred: true,
       reason: "Inferred from legacy roadmap fields."
     };
@@ -9097,7 +9236,7 @@ function parseWorkItemSource(frontmatter) {
   if (frontmatter.source_id) {
     return {
       type: "unknown",
-      id: optStr2(frontmatter.source_id),
+      id: optStr3(frontmatter.source_id),
       inferred: true,
       reason: "Has source_id but no source type."
     };
@@ -9113,7 +9252,7 @@ function renderSourceCompact(source3) {
   if (source3.id) parts.push(source3.id);
   return parts.join(" \xB7 ");
 }
-function optStr2(v) {
+function optStr3(v) {
   if (typeof v === "string" && v.trim()) return v.trim();
   return void 0;
 }
@@ -9686,7 +9825,7 @@ function renderRouteCompact(route) {
 }
 
 // ../cli/src/core/metadata-health.ts
-import matter11 from "gray-matter";
+import matter12 from "gray-matter";
 var KNOWLEDGE_FILES2 = [
   "knowledge/business/business.md",
   "knowledge/product/product.md",
@@ -9706,7 +9845,7 @@ function analyzeMetadataHealth(dir) {
     let data;
     try {
       const raw = readFile(p);
-      data = matter11(raw).data;
+      data = matter12(raw).data;
     } catch {
       continue;
     }
@@ -9738,7 +9877,7 @@ function analyzeMetadataHealth(dir) {
         if (isFile(p) && entry.endsWith(".md")) {
           try {
             const raw = readFile(p);
-            const fm = matter11(raw).data;
+            const fm = matter12(raw).data;
             if (fm.status === "done") {
               const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
               findings.push({
@@ -10505,7 +10644,7 @@ function renderExplanationAgent(exp) {
 var HISTORY_DIR = ".kaddo/history";
 var RUNS_PATH = `${HISTORY_DIR}/guard-runs.jsonl`;
 var SUMMARY_PATH = `${HISTORY_DIR}/guard-summary.json`;
-function toPosix6(p) {
+function toPosix7(p) {
   return p.replace(/\\/g, "/");
 }
 function loadGuardRuns(dir) {
@@ -10542,7 +10681,7 @@ function resolveDriftThreads(runs) {
     let resolvedAt;
     for (const r2 of sorted) {
       if (r2.generated_at <= lastWarn) continue;
-      const touched = r2.touched_files.some((f3) => toPosix6(f3) === codePath);
+      const touched = r2.touched_files.some((f3) => toPosix7(f3) === codePath);
       const warnedHere = r2.warnings.some((x2) => x2.code_path === codePath);
       const updatedRelated = r2.updated_artifacts.some((a2) => related.has(a2));
       if (touched && updatedRelated && !warnedHere) {
@@ -10759,7 +10898,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter12(readFile(wi.filePath)).content;
+      const body = matter13(readFile(wi.filePath)).content;
       if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
       else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
       if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -11752,25 +11891,25 @@ function serializeDriftJson(r2) {
 }
 
 // src/workitems.ts
-import matter13 from "gray-matter";
+import matter14 from "gray-matter";
 var VALID_SOURCES2 = /* @__PURE__ */ new Set(["manual", "roadmap", "jira", "github", "notion", "xlsx", "csv", "api", "external", "unknown"]);
-function optStr3(v) {
+function optStr4(v) {
   return typeof v === "string" && v.trim() ? v.trim() : void 0;
 }
 function parseSource(data) {
   const rawSource = data.source;
   if (rawSource != null && typeof rawSource === "object" && !Array.isArray(rawSource)) {
     const obj = rawSource;
-    const t = optStr3(obj.type);
+    const t = optStr4(obj.type);
     const type = t && VALID_SOURCES2.has(t) ? t : "unknown";
-    return { type, id: optStr3(obj.id) ?? optStr3(data.source_id), title: optStr3(obj.title) ?? optStr3(data.source_title), url: optStr3(obj.url) ?? optStr3(data.source_url), provider: optStr3(obj.provider) ?? optStr3(data.source_provider), inferred: obj.inferred === true || obj.inferred === "true" };
+    return { type, id: optStr4(obj.id) ?? optStr4(data.source_id), title: optStr4(obj.title) ?? optStr4(data.source_title), url: optStr4(obj.url) ?? optStr4(data.source_url), provider: optStr4(obj.provider) ?? optStr4(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: optStr3(data.source_id), title: optStr3(data.source_title), url: optStr3(data.source_url), provider: optStr3(data.source_provider), inferred: false };
+    return { type: raw, id: optStr4(data.source_id), title: optStr4(data.source_title), url: optStr4(data.source_url), provider: optStr4(data.source_provider), inferred: false };
   }
   if (data.source_work_item_candidate || data.source_roadmap_initiative) {
-    return { type: "roadmap", id: optStr3(data.source_id) ?? optStr3(data.source_work_item_candidate), title: optStr3(data.source_initiative_title), inferred: true };
+    return { type: "roadmap", id: optStr4(data.source_id) ?? optStr4(data.source_work_item_candidate), title: optStr4(data.source_initiative_title), inferred: true };
   }
   return { type: "unknown", inferred: true };
 }
@@ -11843,7 +11982,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter13(raw);
+      parsed = matter14(raw);
     } catch {
       continue;
     }
@@ -12363,14 +12502,14 @@ function getPrompt(root, name) {
 }
 
 // src/tools.ts
-import matter25 from "gray-matter";
+import matter26 from "gray-matter";
 
 // ../cli/dist/core.js
 import fs3 from "fs";
 import path3 from "path";
 import { z as z3 } from "zod";
 import { parse as parseYaml10, stringify as stringifyYaml5 } from "yaml";
-import matter14 from "gray-matter";
+import matter15 from "gray-matter";
 import matter22 from "gray-matter";
 import { parse as parseYaml62, stringify as stringifyYaml42 } from "yaml";
 import { parse as parseYaml22 } from "yaml";
@@ -12381,35 +12520,37 @@ import matter32 from "gray-matter";
 import matter42 from "gray-matter";
 import matter52 from "gray-matter";
 import matter62 from "gray-matter";
+import matter72 from "gray-matter";
 import { parse as parseYaml72 } from "yaml";
 import { createHash as createHash2 } from "crypto";
-import matter72 from "gray-matter";
 import matter82 from "gray-matter";
+import matter92 from "gray-matter";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { dirname as dirname2, join as join22, parse as parse2 } from "path";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import matter92 from "gray-matter";
 import matter102 from "gray-matter";
-import { parse as parseYaml82 } from "yaml";
 import matter112 from "gray-matter";
-import matter122 from "gray-matter";
+import { parse as parseYaml82 } from "yaml";
 import matter132 from "gray-matter";
+import matter122 from "gray-matter";
+import matter142 from "gray-matter";
+import matter152 from "gray-matter";
+import matter16 from "gray-matter";
 import { parse as parseYaml92, stringify as stringifyYaml52 } from "yaml";
 import fs4 from "fs";
 import path4 from "path";
 import crypto2 from "crypto";
-import matter142 from "gray-matter";
+import matter17 from "gray-matter";
 import crypto3 from "crypto";
 import fs5 from "fs";
-import matter15 from "gray-matter";
-import matter16 from "gray-matter";
-import { parse as parseYaml102, stringify as stringifyYaml6 } from "yaml";
-import { parse as parseYaml11, stringify as stringifyYaml7 } from "yaml";
-import matter17 from "gray-matter";
 import matter18 from "gray-matter";
 import matter19 from "gray-matter";
+import { parse as parseYaml102, stringify as stringifyYaml6 } from "yaml";
+import { parse as parseYaml11, stringify as stringifyYaml7 } from "yaml";
 import matter20 from "gray-matter";
 import matter21 from "gray-matter";
+import matter222 from "gray-matter";
+import matter23 from "gray-matter";
 function exists2(p) {
   return fs3.existsSync(p);
 }
@@ -12585,7 +12726,7 @@ function parseImpactAnalysis2(data) {
 }
 function parseArtifact2(filePath, raw) {
   try {
-    const { data } = matter14(raw);
+    const { data } = matter15(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -12678,16 +12819,16 @@ function emptyLifecycleCounts2() {
   return Object.fromEntries(LIFECYCLE_STATES3.map((s) => [s, 0]));
 }
 var ARCH_DIR3 = "knowledge";
-function toPosix7(p) {
+function toPosix8(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeTo2(dir, filePath) {
-  const base = toPosix7(dir).replace(/\/+$/, "");
-  const full = toPosix7(filePath);
+  const base = toPosix8(dir).replace(/\/+$/, "");
+  const full = toPosix8(filePath);
   return full.startsWith(base + "/") ? full.slice(base.length + 1) : full;
 }
 function isWorkItemArtifact2(a2) {
-  return toPosix7(a2.filePath).includes("/delivery/work-items/") && Boolean(a2.type);
+  return toPosix8(a2.filePath).includes("/delivery/work-items/") && Boolean(a2.type);
 }
 function classifyLayer2(posixPath) {
   if (posixPath.includes("/knowledge/business/")) return "business";
@@ -12699,7 +12840,7 @@ function classifyLayer2(posixPath) {
   return "unknown";
 }
 function enrich2(dir, a2) {
-  const posix22 = toPosix7(a2.filePath);
+  const posix22 = toPosix8(a2.filePath);
   const isWi = isWorkItemArtifact2(a2);
   return {
     ...a2,
@@ -13960,12 +14101,12 @@ function isValidInitiativeTransition(from, to) {
 function toPosix22(p) {
   return p.replace(/\\/g, "/");
 }
-function optStr4(v) {
+function optStr5(v) {
   if (typeof v === "string" && v.trim()) return v.trim();
   if (typeof v === "number") return String(v);
   return void 0;
 }
-function strList2(v) {
+function strList3(v) {
   if (!Array.isArray(v)) return [];
   return v.map((x2) => typeof x2 === "string" ? x2.trim() : String(x2)).filter(Boolean);
 }
@@ -13976,19 +14117,19 @@ function parseCandidates2(data) {
   for (const entry of raw) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
     const o2 = entry;
-    const id = optStr4(o2.id);
-    const title = optStr4(o2.title);
+    const id = optStr5(o2.id);
+    const title = optStr5(o2.title);
     if (!id || !title) continue;
     out.push({
       id,
       title,
-      type: optStr4(o2.type),
-      suggestedKnowledgeLevel: optStr4(o2.suggested_knowledge_level ?? o2.knowledge_level),
-      expectedValue: optStr4(o2.expected_value),
-      notes: optStr4(o2.notes),
-      sourceSignals: strList2(o2.source_signals),
-      dependencies: strList2(o2.dependencies),
-      materializedAs: optStr4(o2.materialized_as) ?? null
+      type: optStr5(o2.type),
+      suggestedKnowledgeLevel: optStr5(o2.suggested_knowledge_level ?? o2.knowledge_level),
+      expectedValue: optStr5(o2.expected_value),
+      notes: optStr5(o2.notes),
+      sourceSignals: strList3(o2.source_signals),
+      dependencies: strList3(o2.dependencies),
+      materializedAs: optStr5(o2.materialized_as) ?? null
     });
   }
   return out;
@@ -14000,15 +14141,15 @@ function parseExternalLinks2(data) {
   for (const entry of raw) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
     const o2 = entry;
-    const integration = optStr4(o2.integration);
-    const externalId = optStr4(o2.external_id);
+    const integration = optStr5(o2.integration);
+    const externalId = optStr5(o2.external_id);
     if (!integration || !externalId) continue;
     out.push({
       integration,
       externalId,
-      externalType: optStr4(o2.external_type),
-      url: optStr4(o2.url),
-      externalStatus: optStr4(o2.external_status)
+      externalType: optStr5(o2.external_type),
+      url: optStr5(o2.url),
+      externalStatus: optStr5(o2.external_status)
     });
   }
   return out;
@@ -14021,23 +14162,26 @@ function parseInitiative2(dir, filePath, raw) {
     return null;
   }
   const data = parsed.data;
-  if (optStr4(data.type) !== "initiative") return null;
-  const id = optStr4(data.id);
+  if (optStr5(data.type) !== "initiative") return null;
+  const id = optStr5(data.id);
   if (!id) return null;
-  const statusRaw = optStr4(data.status) ?? "planned";
+  const statusRaw = optStr5(data.status) ?? "planned";
   const status = isValidInitiativeStatus2(statusRaw) ? statusRaw : "planned";
   return {
     id,
-    title: optStr4(data.title) ?? id,
+    title: optStr5(data.title) ?? id,
     status,
-    horizon: optStr4(data.horizon) ?? null,
-    priority: optStr4(data.priority) ?? null,
-    knowledgeLevel: optStr4(data.knowledge_level) ?? null,
-    domains: strList2(data.domains),
-    relatedCapabilities: strList2(data.related_capabilities),
-    source: optStr4(data.source) ?? null,
-    sourceId: optStr4(data.source_id) ?? null,
-    createdAt: optStr4(data.created_at) ?? null,
+    horizon: optStr5(data.horizon) ?? null,
+    priority: optStr5(data.priority) ?? null,
+    knowledgeLevel: optStr5(data.knowledge_level) ?? null,
+    domains: strList3(data.domains),
+    relatedCapabilities: strList3(data.related_capabilities),
+    source: optStr5(data.source) ?? null,
+    sourceId: optStr5(data.source_id) ?? null,
+    createdAt: optStr5(data.created_at) ?? null,
+    epic: optStr5(data.epic) ?? null,
+    owners: strList3(data.owners),
+    contributors: strList3(data.contributors),
     externalLinks: parseExternalLinks2(data),
     candidates: parseCandidates2(data),
     filePath,
@@ -14139,6 +14283,290 @@ function suggestInitiativesForExternalItem(dir, integration, externalId) {
     )
   );
 }
+var DELIVERY_PLANS_DIR2 = "knowledge/delivery/plans";
+var EPICS_DIR2 = "knowledge/delivery/epics";
+var PLAN_STATES2 = ["draft", "in-progress", "completed", "cancelled"];
+var EPIC_STATES2 = ["planned", "in-progress", "completed", "cancelled"];
+function toPosix32(p) {
+  return p.replace(/\\/g, "/");
+}
+function optStr22(v) {
+  if (typeof v === "string" && v.trim()) return v.trim();
+  if (typeof v === "number") return String(v);
+  return void 0;
+}
+function strList22(v) {
+  if (!Array.isArray(v)) return [];
+  return v.map((x2) => typeof x2 === "string" ? x2.trim() : String(x2)).filter(Boolean);
+}
+function relFrom2(dir, filePath) {
+  const d3 = toPosix32(dir);
+  const f3 = toPosix32(filePath);
+  return f3.startsWith(d3 + "/") ? f3.slice(d3.length + 1) : f3;
+}
+function parseMilestones2(data) {
+  const raw = data.milestones;
+  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 = optStr22(o2.id);
+    if (!id) continue;
+    out.push({ id, title: optStr22(o2.title) ?? id, exitCriteria: strList22(o2.exit_criteria) });
+  }
+  return out;
+}
+function parseDeliveryPlan2(dir, filePath, raw) {
+  let parsed;
+  try {
+    parsed = matter42(raw, {});
+  } catch {
+    return null;
+  }
+  const data = parsed.data;
+  if (optStr22(data.type) !== "delivery-plan") return null;
+  const id = optStr22(data.id);
+  if (!id) return null;
+  const statusRaw = optStr22(data.status) ?? "draft";
+  const status = PLAN_STATES2.includes(statusRaw) ? statusRaw : "draft";
+  return {
+    id,
+    title: optStr22(data.title) ?? id,
+    status,
+    objective: optStr22(data.objective) ?? null,
+    milestones: parseMilestones2(data),
+    dependsOn: strList22(data.depends_on),
+    successCriteria: strList22(data.success_criteria),
+    risks: strList22(data.risks),
+    references: strList22(data.references),
+    filePath,
+    relPath: relFrom2(dir, filePath),
+    body: parsed.content.trim(),
+    rawFrontmatter: data
+  };
+}
+function parseEpic2(dir, filePath, raw) {
+  let parsed;
+  try {
+    parsed = matter42(raw, {});
+  } catch {
+    return null;
+  }
+  const data = parsed.data;
+  if (optStr22(data.type) !== "epic") return null;
+  const id = optStr22(data.id);
+  if (!id) return null;
+  const statusRaw = optStr22(data.status) ?? "planned";
+  const status = EPIC_STATES2.includes(statusRaw) ? statusRaw : "planned";
+  return {
+    id,
+    title: optStr22(data.title) ?? id,
+    status,
+    outcome: optStr22(data.outcome ?? data.expected_outcome) ?? null,
+    plan: optStr22(data.plan) ?? null,
+    milestone: optStr22(data.milestone) ?? null,
+    dependsOn: strList22(data.depends_on),
+    successCriteria: strList22(data.success_criteria),
+    relatedCapabilities: strList22(data.related_capabilities),
+    decisions: strList22(data.decisions),
+    filePath,
+    relPath: relFrom2(dir, filePath),
+    body: parsed.content.trim(),
+    rawFrontmatter: data
+  };
+}
+function discoverIn2(dir, rel, parse22) {
+  const d3 = join3(dir, rel);
+  if (!exists2(d3)) return [];
+  const out = [];
+  for (const entry of readDir2(d3)) {
+    if (!entry.endsWith(".md")) continue;
+    const full = join3(d3, entry);
+    if (!isFile2(full)) continue;
+    const parsed = parse22(dir, full, readFile2(full));
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+function discoverDeliveryPlans2(dir) {
+  return discoverIn2(dir, DELIVERY_PLANS_DIR2, parseDeliveryPlan2).sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+function discoverEpics2(dir) {
+  return discoverIn2(dir, EPICS_DIR2, parseEpic2).sort((a2, b2) => a2.id.localeCompare(b2.id));
+}
+function getPlan(dir, id) {
+  const want = id.trim().toLowerCase();
+  return discoverDeliveryPlans2(dir).find((p) => p.id.toLowerCase() === want) ?? null;
+}
+function getEpic(dir, id) {
+  const want = id.trim().toLowerCase();
+  return discoverEpics2(dir).find((e) => e.id.toLowerCase() === want) ?? null;
+}
+function nextId(ids, prefix) {
+  let max = 0;
+  for (const id of ids) {
+    const m2 = id.match(new RegExp(`^${prefix}-(\\d+)$`, "i"));
+    if (m2) max = Math.max(max, Number.parseInt(m2[1], 10));
+  }
+  return `${prefix}-${String(max + 1).padStart(3, "0")}`;
+}
+function nextPlanId(dir) {
+  return nextId(discoverDeliveryPlans2(dir).map((p) => p.id), "PLAN");
+}
+function nextEpicId(dir) {
+  return nextId(discoverEpics2(dir).map((e) => e.id), "EP");
+}
+function epicsInPlan(dir, planId) {
+  return discoverEpics2(dir).filter((e) => e.plan?.toLowerCase() === planId.toLowerCase());
+}
+function initiativesInEpic(dir, epicId) {
+  return discoverInitiatives2(dir).filter((i) => i.epic?.toLowerCase() === epicId.toLowerCase());
+}
+function wiEpic(wi) {
+  return optStr22(wi.rawFrontmatter?.epic);
+}
+function workItemsInEpic(dir, epicId) {
+  const iniIds = new Set(initiativesInEpic(dir, epicId).map((i) => i.id.toLowerCase()));
+  return discoverWorkItems2(dir).filter(
+    (wi) => wiEpic(wi)?.toLowerCase() === epicId.toLowerCase() || wi.initiative && iniIds.has(wi.initiative.toLowerCase())
+  );
+}
+function readinessOf(successCriteria, blockingDependencies, delivery) {
+  const committedWorkComplete = delivery.total > 0 && delivery.completed === delivery.total;
+  return {
+    successCriteria,
+    blockingDependencies,
+    committedWorkComplete,
+    // Needs real deliverables, declared criteria and no blocking dependency — never positive otherwise.
+    meetsCompletionPreconditions: committedWorkComplete && successCriteria > 0 && blockingDependencies.length === 0,
+    humanApprovalRequired: true
+    // completion is never automatic
+  };
+}
+function deliveryOf(wis, dir) {
+  const byState = emptyLifecycleCounts2();
+  const completedIds = new Set(
+    discoverWorkItems2(dir).filter((w3) => w3.lifecycle === "completed").map((w3) => w3.id.toLowerCase())
+  );
+  let blocked = 0;
+  for (const wi of wis) {
+    const state = wi.lifecycle ?? "ready";
+    byState[state]++;
+    const deps = strList22(wi.rawFrontmatter?.depends_on);
+    if (state !== "completed" && deps.some((d3) => !completedIds.has(d3.toLowerCase()))) blocked++;
+  }
+  return { total: wis.length, byState, blocked, completed: byState.completed };
+}
+function computeEpicProgress(dir, epic) {
+  const inis = initiativesInEpic(dir, epic.id);
+  const candidates = inis.reduce((n, i) => n + i.candidates.length, 0);
+  const materialized = inis.reduce((n, i) => n + i.candidates.filter((c) => c.materializedAs).length, 0);
+  const wis = workItemsInEpic(dir, epic.id);
+  const delivery = deliveryOf(wis, dir);
+  return {
+    epic: epic.id,
+    status: epic.status,
+    planning: { initiatives: inis.length, candidates, materialized, remaining: Math.max(0, candidates - materialized) },
+    delivery,
+    readiness: readinessOf(epic.successCriteria.length, unmetDependencies(dir, epic.dependsOn), delivery)
+  };
+}
+function computePlanProgress(dir, plan) {
+  const epics = epicsInPlan(dir, plan.id);
+  const byStatus = Object.fromEntries(EPIC_STATES2.map((s) => [s, 0]));
+  for (const e of epics) byStatus[e.status]++;
+  const inis = /* @__PURE__ */ new Map();
+  const wis = /* @__PURE__ */ new Map();
+  for (const e of epics) {
+    for (const i of initiativesInEpic(dir, e.id)) inis.set(i.id, i);
+    for (const w3 of workItemsInEpic(dir, e.id)) wis.set(w3.id, w3);
+  }
+  const candidates = [...inis.values()].reduce((n, i) => n + i.candidates.length, 0);
+  const materialized = [...inis.values()].reduce((n, i) => n + i.candidates.filter((c) => c.materializedAs).length, 0);
+  const delivery = deliveryOf([...wis.values()], dir);
+  return {
+    plan: plan.id,
+    status: plan.status,
+    epics: { total: epics.length, byStatus },
+    planning: { initiatives: inis.size, candidates, materialized, remaining: Math.max(0, candidates - materialized) },
+    delivery,
+    readiness: readinessOf(plan.successCriteria.length, unmetDependencies(dir, plan.dependsOn), delivery),
+    milestones: plan.milestones.map((m2) => ({ id: m2.id, title: m2.title, exitCriteria: m2.exitCriteria.length }))
+  };
+}
+function unmetDependencies(dir, deps) {
+  if (deps.length === 0) return [];
+  const done = /* @__PURE__ */ new Set();
+  for (const e of discoverEpics2(dir)) if (e.status === "completed") done.add(e.id.toLowerCase());
+  for (const p of discoverDeliveryPlans2(dir)) if (p.status === "completed") done.add(p.id.toLowerCase());
+  for (const i of discoverInitiatives2(dir)) if (i.status === "completed") done.add(i.id.toLowerCase());
+  return deps.filter((d3) => !done.has(d3.toLowerCase()));
+}
+function findCycle(nodes, edges) {
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const dfs = (n) => {
+    state.set(n, 1);
+    stack.push(n);
+    for (const m2 of edges.get(n) ?? []) {
+      if (!nodes.includes(m2)) continue;
+      const s = state.get(m2) ?? 0;
+      if (s === 1) return [...stack.slice(stack.indexOf(m2)), m2];
+      if (s === 0) {
+        const c = dfs(m2);
+        if (c) return c;
+      }
+    }
+    stack.pop();
+    state.set(n, 2);
+    return null;
+  };
+  for (const n of nodes) if ((state.get(n) ?? 0) === 0) {
+    const c = dfs(n);
+    if (c) return c;
+  }
+  return null;
+}
+function validatePlanningGraph(dir) {
+  const plans = discoverDeliveryPlans2(dir);
+  const epics = discoverEpics2(dir);
+  const inis = discoverInitiatives2(dir);
+  const planIds = new Set(plans.map((p) => p.id.toLowerCase()));
+  const epicIds = new Set(epics.map((e) => e.id.toLowerCase()));
+  const iniIds = new Set(inis.map((i) => i.id.toLowerCase()));
+  const findings = [];
+  for (const p of plans) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const m2 of p.milestones) {
+      const key = m2.id.toLowerCase();
+      if (seen.has(key))
+        findings.push({ level: "error", kind: "duplicate_milestone", subject: p.id, message: `Plan ${p.id} declares milestone ${m2.id} more than once.` });
+      seen.add(key);
+    }
+  }
+  for (const e of epics) {
+    if (e.plan && !planIds.has(e.plan.toLowerCase()))
+      findings.push({ level: "error", kind: "invalid_reference", subject: e.id, message: `Epic ${e.id} references missing plan ${e.plan}.` });
+    if (e.plan && e.milestone) {
+      const plan = plans.find((p) => p.id.toLowerCase() === e.plan.toLowerCase());
+      if (plan && !plan.milestones.some((m2) => m2.id.toLowerCase() === e.milestone.toLowerCase()))
+        findings.push({ level: "error", kind: "invalid_reference", subject: e.id, message: `Epic ${e.id} references milestone ${e.milestone} not defined in ${e.plan}.` });
+    }
+    for (const d3 of e.dependsOn) if (!epicIds.has(d3.toLowerCase()))
+      findings.push({ level: "error", kind: "invalid_reference", subject: e.id, message: `Epic ${e.id} depends on missing Epic ${d3}.` });
+  }
+  for (const i of inis) {
+    if (i.epic && !epicIds.has(i.epic.toLowerCase()))
+      findings.push({ level: "error", kind: "invalid_reference", subject: i.id, message: `Initiative ${i.id} references missing Epic ${i.epic}.` });
+  }
+  const epicEdges = new Map(epics.map((e) => [e.id.toLowerCase(), e.dependsOn.map((d3) => d3.toLowerCase())]));
+  const epicCycle = findCycle([...epicIds], epicEdges);
+  if (epicCycle) findings.push({ level: "error", kind: "dependency_cycle", subject: epicCycle[0], message: `Dependency cycle among Epics: ${epicCycle.join(" \u2192 ")}.` });
+  for (const e of epics) for (const d3 of unmetDependencies(dir, e.dependsOn))
+    findings.push({ level: "warning", kind: "pending_dependency", subject: e.id, message: `Epic ${e.id} is blocked by unfinished dependency ${d3}.` });
+  return findings;
+}
 var RESOURCE_ARTIFACT_TYPE2 = "project-resource";
 var REDACTED_COORDINATE2 = "\u2022\u2022\u2022\u2022 (hidden \u2014 store as an authentication reference)";
 var SECRET_KEY_RE2 = /(pass(word|phrase)?|secret|token|api[_-]?key|\bkey\b|credential|private|auth[_-]?token|access[_-]?key)/i;
@@ -14242,7 +14670,7 @@ function purposeFromBody3(body) {
   return text22 || null;
 }
 function toDetail2(filePath, relPath, raw) {
-  const parsed = matter42(raw);
+  const parsed = matter52(raw);
   const fm = parsed.data ?? {};
   const body = parsed.content.trim();
   const id = str3(fm.id) ?? "";
@@ -14458,7 +14886,7 @@ function getDeprecationPlan2(dir, id) {
   );
   if (!match) return null;
   const raw = readFile2(match.filePath);
-  const parsed = matter52(raw);
+  const parsed = matter62(raw);
   const fm = parsed.data ?? {};
   const body = parsed.content.trim();
   const targets = parseTargets2(fm.targets);
@@ -14486,14 +14914,14 @@ var ALL_STATUSES2 = ["draft", "ready", "in-progress", "blocked", "completed"];
 function scopeStatuses2(scope) {
   return scope === "all" ? { included: ALL_STATUSES2, excluded: ["archived"] } : { included: ACTIVE_STATUSES2, excluded: ["completed", "archived"] };
 }
-function toPosix32(p) {
+function toPosix42(p) {
   return p.replace(/\\/g, "/");
 }
 function slug3(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr3(a2) {
-  return toPosix32(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
+  return toPosix42(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
 }
 function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   const scope = opts.scope ?? "active";
@@ -14604,6 +15032,27 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
   }
+  for (const plan of discoverDeliveryPlans2(dir)) {
+    const planId = `delivery-plan:${slug3(plan.id) || plan.id}`;
+    addNode({ id: planId, type: "delivery-plan", label: `${plan.id} ${plan.title}`.trim(), path: plan.relPath, status: plan.status });
+    for (const m2 of plan.milestones) {
+      const milestoneId = `milestone:${slug3(plan.id)}:${slug3(m2.id) || m2.id}`;
+      addNode({ id: milestoneId, type: "milestone", label: `${m2.id} ${m2.title}`.trim(), path: plan.relPath });
+      addEdge(milestoneId, planId, "belongs_to");
+    }
+  }
+  for (const epic of discoverEpics2(dir)) {
+    const epicNodeId = `epic:${slug3(epic.id) || epic.id}`;
+    addNode({ id: epicNodeId, type: "epic", label: `${epic.id} ${epic.title}`.trim(), path: epic.relPath, status: epic.status });
+    if (epic.plan) {
+      addEdge(epicNodeId, `delivery-plan:${slug3(epic.plan)}`, "belongs_to");
+      if (epic.milestone) addEdge(epicNodeId, `milestone:${slug3(epic.plan)}:${slug3(epic.milestone)}`, "belongs_to");
+    }
+    for (const dep of epic.dependsOn) addEdge(epicNodeId, `epic:${slug3(dep)}`, "depends_on");
+  }
+  for (const ini of discoverInitiatives2(dir)) {
+    if (ini.epic) addEdge(`initiative:${slug3(ini.id) || ini.id}`, `epic:${slug3(ini.epic)}`, "belongs_to");
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -14708,14 +15157,14 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   };
 }
 var KNOWLEDGE32 = "knowledge";
-function toPosix42(p) {
+function toPosix52(p) {
   return p.replace(/\\/g, "/");
 }
 function slug22(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function isAdr22(a2) {
-  return toPosix42(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
+  return toPosix52(a2.filePath).includes("/tech/decisions/") && Boolean(a2.type);
 }
 function capabilityHeadings2(dir) {
   const p = join3(dir, KNOWLEDGE32, "product", "capabilities.md");
@@ -15048,7 +15497,7 @@ function reportFiles2(dir) {
     const match = name.match(reportName2);
     if (!match) return [];
     try {
-      const parsed = matter72(readFile2(join3(delivery, name)));
+      const parsed = matter82(readFile2(join3(delivery, name)));
       const fingerprint = typeof parsed.data.source_fingerprint === "string" ? parsed.data.source_fingerprint : "";
       const manifest = parsed.data.source_manifest;
       const sourceManifest = manifest && typeof manifest === "object" && !Array.isArray(manifest) ? Object.fromEntries(Object.entries(manifest).filter(([, digest]) => typeof digest === "string")) : {};
@@ -15147,7 +15596,7 @@ function canonicalReport(context, proposal) {
     source_manifest: Object.fromEntries(context.sources.map((item) => [item.path, item.digest]))
   };
   if (supersedes) data.supersedes = supersedes;
-  return matter72.stringify(redactSecrets2(proposal).trimEnd() + "\n", data);
+  return matter82.stringify(redactSecrets2(proposal).trimEnd() + "\n", data);
 }
 function persistPocReport(dir, proposal, opts = {}) {
   const context = buildPocReportContext2(dir);
@@ -16111,9 +16560,9 @@ var RESPONSIBILITY_MATRIX2 = {
   },
   "roadmap-agent": {
     agent: "roadmap-agent",
-    responsibleFor: ["Roadmap", "Initiatives", "Work Item candidates"],
+    responsibleFor: ["Roadmap", "Initiatives", "Work Item candidates", "Delivery Plans and Epics (optional planning layer)"],
     produces: ["knowledge/delivery/roadmap.md"],
-    canSuggest: ["kaddo create --from roadmap", "work-item-agent"],
+    canSuggest: ["kaddo create --from roadmap", "work-item-agent", "kaddo plan create", "kaddo epic create"],
     cannotSuggest: ["branches", "commits", "pull requests", "code"],
     next: ["kaddo create --from roadmap", "work-item-agent"]
   },
@@ -18616,19 +19065,19 @@ function parseWorkItemSource2(frontmatter2) {
   const rawSource = frontmatter2.source;
   if (rawSource != null && typeof rawSource === "object" && !Array.isArray(rawSource)) {
     const obj = rawSource;
-    const t = optStr22(obj.type);
+    const t = optStr32(obj.type);
     const type = t && isValidSource2(t) ? t : "unknown";
     return {
       type,
-      id: optStr22(obj.id) ?? optStr22(frontmatter2.source_id),
-      title: optStr22(obj.title) ?? optStr22(frontmatter2.source_title),
-      context: optStr22(obj.context) ?? optStr22(frontmatter2.source_context),
-      provider: optStr22(obj.provider) ?? optStr22(frontmatter2.source_provider),
-      integration: optStr22(obj.integration) ?? optStr22(frontmatter2.source_integration),
-      url: optStr22(obj.url) ?? optStr22(frontmatter2.source_url),
-      imported_at: optStr22(obj.imported_at) ?? optStr22(frontmatter2.source_imported_at),
-      external_updated_at: optStr22(obj.external_updated_at) ?? optStr22(frontmatter2.source_external_updated_at),
-      synced_at: optStr22(obj.synced_at) ?? optStr22(frontmatter2.source_synced_at),
+      id: optStr32(obj.id) ?? optStr32(frontmatter2.source_id),
+      title: optStr32(obj.title) ?? optStr32(frontmatter2.source_title),
+      context: optStr32(obj.context) ?? optStr32(frontmatter2.source_context),
+      provider: optStr32(obj.provider) ?? optStr32(frontmatter2.source_provider),
+      integration: optStr32(obj.integration) ?? optStr32(frontmatter2.source_integration),
+      url: optStr32(obj.url) ?? optStr32(frontmatter2.source_url),
+      imported_at: optStr32(obj.imported_at) ?? optStr32(frontmatter2.source_imported_at),
+      external_updated_at: optStr32(obj.external_updated_at) ?? optStr32(frontmatter2.source_external_updated_at),
+      synced_at: optStr32(obj.synced_at) ?? optStr32(frontmatter2.source_synced_at),
       inferred: obj.inferred === true || obj.inferred === "true",
       reason: t && !isValidSource2(t) ? `Invalid source type in object: "${t}".` : void 0
     };
@@ -18637,28 +19086,28 @@ function parseWorkItemSource2(frontmatter2) {
   if (raw && isValidSource2(raw)) {
     return {
       type: raw,
-      id: optStr22(frontmatter2.source_id),
-      title: optStr22(frontmatter2.source_title),
-      context: optStr22(frontmatter2.source_context),
-      provider: optStr22(frontmatter2.source_provider),
-      url: optStr22(frontmatter2.source_url),
-      imported_at: optStr22(frontmatter2.source_imported_at),
-      external_updated_at: optStr22(frontmatter2.source_external_updated_at),
-      synced_at: optStr22(frontmatter2.source_synced_at),
+      id: optStr32(frontmatter2.source_id),
+      title: optStr32(frontmatter2.source_title),
+      context: optStr32(frontmatter2.source_context),
+      provider: optStr32(frontmatter2.source_provider),
+      url: optStr32(frontmatter2.source_url),
+      imported_at: optStr32(frontmatter2.source_imported_at),
+      external_updated_at: optStr32(frontmatter2.source_external_updated_at),
+      synced_at: optStr32(frontmatter2.source_synced_at),
       inferred: false
     };
   }
   if (raw && !isValidSource2(raw)) {
     return {
       type: "unknown",
-      id: optStr22(frontmatter2.source_id),
-      title: optStr22(frontmatter2.source_title),
-      context: optStr22(frontmatter2.source_context),
-      provider: optStr22(frontmatter2.source_provider),
-      url: optStr22(frontmatter2.source_url),
-      imported_at: optStr22(frontmatter2.source_imported_at),
-      external_updated_at: optStr22(frontmatter2.source_external_updated_at),
-      synced_at: optStr22(frontmatter2.source_synced_at),
+      id: optStr32(frontmatter2.source_id),
+      title: optStr32(frontmatter2.source_title),
+      context: optStr32(frontmatter2.source_context),
+      provider: optStr32(frontmatter2.source_provider),
+      url: optStr32(frontmatter2.source_url),
+      imported_at: optStr32(frontmatter2.source_imported_at),
+      external_updated_at: optStr32(frontmatter2.source_external_updated_at),
+      synced_at: optStr32(frontmatter2.source_synced_at),
       inferred: true,
       reason: `Invalid source value: "${raw}".`
     };
@@ -18666,8 +19115,8 @@ function parseWorkItemSource2(frontmatter2) {
   if (frontmatter2.source_work_item_candidate || frontmatter2.source_roadmap_initiative) {
     return {
       type: "roadmap",
-      id: optStr22(frontmatter2.source_id) ?? optStr22(frontmatter2.source_work_item_candidate),
-      title: optStr22(frontmatter2.source_initiative_title),
+      id: optStr32(frontmatter2.source_id) ?? optStr32(frontmatter2.source_work_item_candidate),
+      title: optStr32(frontmatter2.source_initiative_title),
       inferred: true,
       reason: "Inferred from legacy roadmap fields."
     };
@@ -18675,7 +19124,7 @@ function parseWorkItemSource2(frontmatter2) {
   if (frontmatter2.source_id) {
     return {
       type: "unknown",
-      id: optStr22(frontmatter2.source_id),
+      id: optStr32(frontmatter2.source_id),
       inferred: true,
       reason: "Has source_id but no source type."
     };
@@ -18686,7 +19135,7 @@ function parseWorkItemSource2(frontmatter2) {
     reason: "No source metadata found."
   };
 }
-function optStr22(v) {
+function optStr32(v) {
   if (typeof v === "string" && v.trim()) return v.trim();
   return void 0;
 }
@@ -18933,17 +19382,387 @@ var LEGACY_STEPS2 = [
 var HISTORY_DIR2 = ".kaddo/history";
 var RUNS_PATH2 = `${HISTORY_DIR2}/guard-runs.jsonl`;
 var SUMMARY_PATH2 = `${HISTORY_DIR2}/guard-summary.json`;
-var USER_FACING_KEYWORDS_EN = [
-  "user",
-  "visitor",
-  "page",
-  "registration",
-  "login",
-  "form",
-  "show",
-  "display",
-  "cta",
-  "flow",
+var WORK_ITEMS_DIR = "knowledge/delivery/work-items";
+var DRAFT_DIR = `${WORK_ITEMS_DIR}/draft`;
+var InitiativeWriteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitiativeWriteError";
+  }
+};
+function slugify22(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;
+  if (l2.externalStatus) out.external_status = l2.externalStatus;
+  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 (!isValidInitiativeStatus2(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;
+  if (input.epic) data.epic = input.epic.trim();
+  if (input.owners?.length) data.owners = input.owners.map((o2) => o2.trim()).filter(Boolean);
+  if (input.contributors?.length) data.contributors = input.contributors.map((c) => c.trim()).filter(Boolean);
+  return matter122.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}-${slugify22(input.title)}.md`;
+  const iniDir = join3(dir, INITIATIVES_DIR2);
+  ensureDir2(iniDir);
+  const filePath = join3(iniDir, fileName);
+  const content = buildInitiativeContent(id, input);
+  writeFile2(filePath, content);
+  const ini = parseInitiative2(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 (!isValidInitiativeStatus2(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 } = matter122(raw, {});
+  data.status = to;
+  if (to === "completed") data.completed_at = today2();
+  const newContent = matter122.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative2(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 } = matter122(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 = matter122.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative2(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 } = matter122(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;
+  if (patch.epic !== void 0) {
+    if (patch.epic === null || patch.epic.trim() === "") delete data.epic;
+    else data.epic = patch.epic.trim();
+  }
+  if (patch.owners !== void 0) data.owners = patch.owners.map((o2) => o2.trim()).filter(Boolean);
+  if (patch.contributors !== void 0) data.contributors = patch.contributors.map((c) => c.trim()).filter(Boolean);
+  const newContent = matter122.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative2(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
+  return updated;
+}
+function addExternalLink(dir, id, link) {
+  const ini = getInitiative(dir, id);
+  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
+  if (!link.integration?.trim() || !link.externalId?.trim()) {
+    throw new InitiativeWriteError("External link requires integration and externalId.");
+  }
+  if (ini.externalLinks.some(
+    (l2) => l2.integration.trim().toLowerCase() === link.integration.trim().toLowerCase() && l2.externalId.trim().toLowerCase() === link.externalId.trim().toLowerCase()
+  )) {
+    throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
+  }
+  const raw = readFile2(ini.filePath);
+  const { data, content } = matter122(raw, {});
+  const existing = Array.isArray(data.external_links) ? data.external_links : [];
+  data.external_links = [...existing, externalLinkToData(link)];
+  const newContent = matter122.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative2(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
+  return updated;
+}
+function nextWorkItemId(dir) {
+  const wiDir = join3(dir, WORK_ITEMS_DIR);
+  let max = 0;
+  const walk2 = (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(".")) {
+        walk2(full);
+      }
+    }
+  };
+  walk2(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 matter122.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 = nextWorkItemId(dir);
+  const fileName = `${wiId}-${slugify22(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 } = matter122(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 = matter122.stringify(content, data);
+  writeFile2(ini.filePath, newContent);
+  const updated = parseInitiative2(dir, ini.filePath, newContent);
+  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
+  return { workItemId: wiId, fileName, initiative: updated };
+}
+var DeliveryPlanningWriteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeliveryPlanningWriteError";
+  }
+};
+function slugify3(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "item";
+}
+function createDeliveryPlan(dir, input) {
+  if (!input.title?.trim()) throw new DeliveryPlanningWriteError("Plan title is required.");
+  const status = input.status ?? "draft";
+  if (!PLAN_STATES2.includes(status)) throw new DeliveryPlanningWriteError(`Invalid plan status: ${status}.`);
+  const id = nextPlanId(dir);
+  const data = { type: "delivery-plan", id, title: input.title.trim(), status, milestones: [] };
+  if (input.objective?.trim()) data.objective = input.objective.trim();
+  const body = `
+# ${input.title.trim()}
+
+_Describe the objective, scope, exclusions, milestones, dependencies, success criteria and risks._
+`;
+  const filePath = join3(dir, DELIVERY_PLANS_DIR2, `${id}-${slugify3(input.title)}.md`);
+  ensureDir2(join3(dir, DELIVERY_PLANS_DIR2));
+  const content = matter132.stringify(body, data);
+  writeFile2(filePath, content);
+  const plan = parseDeliveryPlan2(dir, filePath, content);
+  if (!plan) throw new DeliveryPlanningWriteError("Failed to parse the Plan just written.");
+  return plan;
+}
+function createEpic(dir, input) {
+  if (!input.title?.trim()) throw new DeliveryPlanningWriteError("Epic title is required.");
+  const status = input.status ?? "planned";
+  if (!EPIC_STATES2.includes(status)) throw new DeliveryPlanningWriteError(`Invalid epic status: ${status}.`);
+  if (input.plan) {
+    const plan = getPlan(dir, input.plan);
+    if (!plan) throw new DeliveryPlanningWriteError(`Plan ${input.plan} does not exist.`);
+    if (input.milestone && !plan.milestones.some((m2) => m2.id.toLowerCase() === input.milestone.toLowerCase())) {
+      throw new DeliveryPlanningWriteError(`Milestone ${input.milestone} is not defined in ${input.plan}.`);
+    }
+  } else if (input.milestone) {
+    throw new DeliveryPlanningWriteError("A milestone can only be set together with its plan.");
+  }
+  const id = nextEpicId(dir);
+  const data = { type: "epic", id, title: input.title.trim(), status };
+  if (input.outcome?.trim()) data.outcome = input.outcome.trim();
+  if (input.plan) data.plan = input.plan;
+  if (input.milestone) data.milestone = input.milestone;
+  const body = `
+# ${input.title.trim()}
+
+_Describe the expected outcome, success criteria, dependencies and delivery evidence._
+`;
+  const filePath = join3(dir, EPICS_DIR2, `${id}-${slugify3(input.title)}.md`);
+  ensureDir2(join3(dir, EPICS_DIR2));
+  const content = matter132.stringify(body, data);
+  writeFile2(filePath, content);
+  const epic = parseEpic2(dir, filePath, content);
+  if (!epic) throw new DeliveryPlanningWriteError("Failed to parse the Epic just written.");
+  return epic;
+}
+function associateInitiativeWithEpic(dir, initiativeId, epicId) {
+  const ini = getInitiative(dir, initiativeId);
+  if (!ini) throw new DeliveryPlanningWriteError(`Initiative ${initiativeId} not found.`);
+  if (!getEpic(dir, epicId)) throw new DeliveryPlanningWriteError(`Epic ${epicId} does not exist.`);
+  return updateInitiative(dir, ini.id, { epic: epicId });
+}
+var USER_FACING_KEYWORDS_EN = [
+  "user",
+  "visitor",
+  "page",
+  "registration",
+  "login",
+  "form",
+  "show",
+  "display",
+  "cta",
+  "flow",
   "screen",
   "dashboard",
   "ui",
@@ -19107,7 +19926,7 @@ var PROVENANCE = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewed
 function isRelative(p) {
   return typeof p === "string" && p.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p) && !p.includes("..");
 }
-function strList22(v) {
+function strList32(v) {
   return Array.isArray(v) ? v.map((x2) => typeof x2 === "string" ? x2.trim() : "").filter(Boolean) : [];
 }
 function loadSystemTopology(dir) {
@@ -19148,7 +19967,7 @@ function parseTopologyContent(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 = strList22(rawImpl).filter((p) => {
+    const implementation = strList32(rawImpl).filter((p) => {
       if (isRelative(p)) return true;
       findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p}" is not a safe relative path and was dropped.` });
       return false;
@@ -19156,7 +19975,7 @@ function parseTopologyContent(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 && PROVENANCE.has(provOrigin) ? provOrigin : void 0;
-    const evidence = strList22(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative);
+    const evidence = strList32(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative);
     seenIds.add(id);
     entities.push({
       id,
@@ -19165,7 +19984,7 @@ function parseTopologyContent(raw, dir) {
       ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
       ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
       implementationRefs: implementation,
-      knowledgeRefs: strList22(e.knowledge ?? e.knowledge_refs),
+      knowledgeRefs: strList32(e.knowledge ?? e.knowledge_refs),
       ...provenance ? { provenance } : {},
       evidence
     });
@@ -19199,7 +20018,7 @@ function parseTopologyContent(raw, dir) {
     }
     seenRels.add(key);
     const prov = r2.provenance;
-    relationships.push({ from, to, type, evidence: strList22(r2.evidence ?? prov?.evidence_refs).filter(isRelative) });
+    relationships.push({ from, to, type, evidence: strList32(r2.evidence ?? prov?.evidence_refs).filter(isRelative) });
   }
   return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
 }
@@ -19338,7 +20157,7 @@ function parseOriginalSnapshot(fm) {
 function readBody(filePath) {
   try {
     const raw = readFile2(filePath);
-    return matter132(raw).content;
+    return matter16(raw).content;
   } catch {
     return "";
   }
@@ -19422,7 +20241,7 @@ function normalizeImpact(ia) {
     ...v.question ? { question: v.question } : {}
   }));
 }
-function optStr32(v) {
+function optStr42(v) {
   if (typeof v === "string" && v.trim()) return v.trim();
   return void 0;
 }
@@ -19437,13 +20256,13 @@ function parseEvidence(fm) {
     const validations = Array.isArray(d3.validations) ? d3.validations.map((v) => ({
       command: String(v.command ?? ""),
       status: String(v.status ?? "unknown"),
-      ...optStr32(v.reason) ? { reason: optStr32(v.reason) } : {}
+      ...optStr42(v.reason) ? { reason: optStr42(v.reason) } : {}
     })) : [];
     const migrations = Array.isArray(d3.migrations) ? d3.migrations.map((m2) => ({
       id: String(m2.id ?? ""),
       environment: String(m2.environment ?? ""),
       status: String(m2.status ?? "unknown"),
-      ...optStr32(m2.reason) ? { reason: optStr32(m2.reason) } : {}
+      ...optStr42(m2.reason) ? { reason: optStr42(m2.reason) } : {}
     })) : [];
     out.push({
       module,
@@ -19461,8 +20280,8 @@ function parseReleaseGates(fm) {
   return fm.release_gates.filter((g) => g && typeof g === "object").map((g) => ({
     id: String(g.id ?? ""),
     status: String(g.status ?? "pending"),
-    ...optStr32(g.reason) ? { reason: optStr32(g.reason) } : {},
-    ...optStr32(g.required_for) ? { requiredFor: optStr32(g.required_for) } : {}
+    ...optStr42(g.reason) ? { reason: optStr42(g.reason) } : {},
+    ...optStr42(g.required_for) ? { requiredFor: optStr42(g.required_for) } : {}
   }));
 }
 function parseExceptions(fm) {
@@ -19470,9 +20289,9 @@ function parseExceptions(fm) {
   return fm.completion_exceptions.filter((e) => e && typeof e === "object").map((e) => ({
     id: String(e.id ?? ""),
     status: String(e.status ?? "proposed"),
-    ...optStr32(e.reason) ? { reason: optStr32(e.reason) } : {},
-    ...optStr32(e.category) ? { category: optStr32(e.category) } : {},
-    ...optStr32(e.impact) ? { impact: optStr32(e.impact) } : {}
+    ...optStr42(e.reason) ? { reason: optStr42(e.reason) } : {},
+    ...optStr42(e.category) ? { category: optStr42(e.category) } : {},
+    ...optStr42(e.impact) ? { impact: optStr42(e.impact) } : {}
   }));
 }
 function parseDecisions(decisions, knowledgeById) {
@@ -19520,7 +20339,7 @@ function normalizeType(raw) {
   if (isValidType(t)) return t;
   return TYPE_ALIASES[t] ?? null;
 }
-var WORK_ITEMS_DIR = "knowledge/delivery/work-items";
+var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 var WorkItemWriteError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -19532,11 +20351,11 @@ var WorkItemWriteError = class extends Error {
 function revisionOf(raw) {
   return crypto2.createHash("sha256").update(raw, "utf-8").digest("hex");
 }
-function slugify22(s) {
+function slugify4(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
 }
-function nextWorkItemId(dir) {
-  const wiDir = join3(dir, WORK_ITEMS_DIR);
+function nextWorkItemId2(dir) {
+  const wiDir = join3(dir, WORK_ITEMS_DIR2);
   let max = 0;
   const walk2 = (d3) => {
     if (!exists2(d3)) return;
@@ -19623,7 +20442,7 @@ function ensureH1(body, title) {
 ${trimmed}`;
 }
 function serialize2(data, body) {
-  return matter142.stringify(`
+  return matter17.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -19654,7 +20473,7 @@ function createWorkItem(dir, opts) {
   if (!intent) throw new WorkItemWriteError("INVALID_INPUT", "An intent or summary is required.");
   const type = normalizeType(opts.type.trim()) ?? "";
   if (!type) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${opts.type}".`);
-  const id = nextWorkItemId(dir);
+  const id = nextWorkItemId2(dir);
   const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
   const today22 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = opts.summary?.trim() || intent;
@@ -19688,7 +20507,7 @@ function createWorkItem(dir, opts) {
     relatedKnowledge: [],
     scopeConfidence: null
   });
-  const relPath = `${WORK_ITEMS_DIR}/draft/${id}-${slugify22(title)}.md`;
+  const relPath = `${WORK_ITEMS_DIR2}/draft/${id}-${slugify4(title)}.md`;
   const filePath = join3(dir, relPath);
   if (exists2(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
   const raw = serialize2(data, body);
@@ -20537,7 +21356,7 @@ function detectFormat(raw) {
   if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
   if (trimmed.startsWith("---")) {
     try {
-      const { data } = matter15(trimmed);
+      const { data } = matter18(trimmed);
       if (data && typeof data === "object" && Object.keys(data).length > 0) {
         const d3 = data;
         if (d3.type === "work-item" || d3.id && typeof d3.id === "string" && /^WI-\d+/.test(d3.id)) {
@@ -20559,7 +21378,7 @@ function parseContent(raw) {
   let bodyText = trimmed;
   if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
     try {
-      const parsed = matter15(trimmed);
+      const parsed = matter18(trimmed);
       frontmatterFields = parsed.data ?? {};
       bodyText = parsed.content.trim();
     } catch {
@@ -20656,7 +21475,7 @@ function findDuplicateByHash(dir, hash) {
     const raw = readFile2(item.filePath);
     if (!raw) continue;
     try {
-      const { data } = matter15(raw);
+      const { data } = matter18(raw);
       const source22 = data?.source;
       if (source22 && typeof source22 === "object" && !Array.isArray(source22)) {
         const s = source22;
@@ -21363,377 +22182,82 @@ function getConsentState(config) {
   if (t.consent === "enabled") return "enabled";
   if (t.consent === "disabled") return "disabled";
   if (t.consent === void 0) {
-    if (t.enabled === true) return "enabled";
-    if (t.enabled === false) return "disabled";
-  }
-  return "unset";
-}
-function persistConsent(dir, consent) {
-  const configPath = join3(dir, ".kaddo", "config.yml");
-  if (!exists2(configPath)) return;
-  const raw = readFile2(configPath);
-  const doc = parseYaml11(raw) ?? {};
-  const prev = doc.telemetry ?? {};
-  delete prev.enabled;
-  doc.telemetry = { ...prev, consent, consentVersion: CURRENT_CONSENT_VERSION };
-  writeFile2(configPath, stringifyYaml7(doc));
-}
-function isDeferralActive(dir) {
-  const p = join3(dir, ".kaddo", "telemetry-deferred.json");
-  if (!exists2(p)) return false;
-  try {
-    const data = JSON.parse(readFile2(p));
-    return data.deferredUntil > Date.now();
-  } catch {
-    return false;
-  }
-}
-function deferConsent(dir) {
-  const p = join3(dir, ".kaddo", "telemetry-deferred.json");
-  writeFile2(p, JSON.stringify({ deferredUntil: Date.now() + DEFERRAL_DURATION_MS }));
-}
-function consentNotice() {
-  return '[Telemetry consent] Anonymous usage telemetry has not been configured.\n  Collects: command usage, version, lifecycle events.\n  Never collects: source code, knowledge, prompts or PII.\n  Use kaddo_set_telemetry_consent to enable, disable, or defer ("not-now").';
-}
-var TELEMETRY_DIR = ".kaddo/telemetry";
-var IDENTITY_FILE = "identity.json";
-function identityPath(dir) {
-  return join3(dir, TELEMETRY_DIR, IDENTITY_FILE);
-}
-function loadIdentity(dir) {
-  const p = identityPath(dir);
-  if (!exists2(p)) return null;
-  try {
-    return JSON.parse(readFile2(p));
-  } catch {
-    return null;
-  }
-}
-var TELEMETRY_DIR2 = ".kaddo/telemetry";
-var BUFFER_FILE = "buffer.json";
-function bufferPath(dir) {
-  return join3(dir, TELEMETRY_DIR2, BUFFER_FILE);
-}
-function readBuffer(dir) {
-  const p = bufferPath(dir);
-  if (!exists2(p)) return [];
-  try {
-    const data = JSON.parse(readFile2(p));
-    return Array.isArray(data) ? data : [];
-  } catch {
-    return [];
-  }
-}
-function bufferSize(dir) {
-  return readBuffer(dir).length;
-}
-function getStatus(dir) {
-  const config = loadConfig2(dir);
-  const consent = getConsentState(config);
-  const enabled = consent === "enabled";
-  const identity = loadIdentity(dir);
-  return {
-    consent,
-    enabled,
-    registered: identity?.registered ?? false,
-    pendingEvents: enabled ? bufferSize(dir) : 0,
-    lastError: null
-  };
-}
-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;
-  if (l2.externalStatus) out.external_status = l2.externalStatus;
-  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 (!isValidInitiativeStatus2(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 matter17.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_DIR2);
-  ensureDir2(iniDir);
-  const filePath = join3(iniDir, fileName);
-  const content = buildInitiativeContent(id, input);
-  writeFile2(filePath, content);
-  const ini = parseInitiative2(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 (!isValidInitiativeStatus2(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 } = matter17(raw, {});
-  data.status = to;
-  if (to === "completed") data.completed_at = today2();
-  const newContent = matter17.stringify(content, data);
-  writeFile2(ini.filePath, newContent);
-  const updated = parseInitiative2(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 } = matter17(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}.`);
+    if (t.enabled === true) return "enabled";
+    if (t.enabled === false) return "disabled";
   }
-  data.candidates = [...existing, candidateToData(normalized)];
-  const newContent = matter17.stringify(content, data);
-  writeFile2(ini.filePath, newContent);
-  const updated = parseInitiative2(dir, ini.filePath, newContent);
-  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
-  return updated;
+  return "unset";
 }
-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 } = matter17(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 = matter17.stringify(content, data);
-  writeFile2(ini.filePath, newContent);
-  const updated = parseInitiative2(dir, ini.filePath, newContent);
-  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
-  return updated;
+function persistConsent(dir, consent) {
+  const configPath = join3(dir, ".kaddo", "config.yml");
+  if (!exists2(configPath)) return;
+  const raw = readFile2(configPath);
+  const doc = parseYaml11(raw) ?? {};
+  const prev = doc.telemetry ?? {};
+  delete prev.enabled;
+  doc.telemetry = { ...prev, consent, consentVersion: CURRENT_CONSENT_VERSION };
+  writeFile2(configPath, stringifyYaml7(doc));
 }
-function addExternalLink(dir, id, link) {
-  const ini = getInitiative(dir, id);
-  if (!ini) throw new InitiativeWriteError(`Initiative ${id} not found.`);
-  if (!link.integration?.trim() || !link.externalId?.trim()) {
-    throw new InitiativeWriteError("External link requires integration and externalId.");
-  }
-  if (ini.externalLinks.some(
-    (l2) => l2.integration.trim().toLowerCase() === link.integration.trim().toLowerCase() && l2.externalId.trim().toLowerCase() === link.externalId.trim().toLowerCase()
-  )) {
-    throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
+function isDeferralActive(dir) {
+  const p = join3(dir, ".kaddo", "telemetry-deferred.json");
+  if (!exists2(p)) return false;
+  try {
+    const data = JSON.parse(readFile2(p));
+    return data.deferredUntil > Date.now();
+  } catch {
+    return false;
   }
-  const raw = readFile2(ini.filePath);
-  const { data, content } = matter17(raw, {});
-  const existing = Array.isArray(data.external_links) ? data.external_links : [];
-  data.external_links = [...existing, externalLinkToData(link)];
-  const newContent = matter17.stringify(content, data);
-  writeFile2(ini.filePath, newContent);
-  const updated = parseInitiative2(dir, ini.filePath, newContent);
-  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
-  return updated;
 }
-function nextWorkItemId2(dir) {
-  const wiDir = join3(dir, WORK_ITEMS_DIR2);
-  let max = 0;
-  const walk2 = (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(".")) {
-        walk2(full);
-      }
-    }
-  };
-  walk2(wiDir);
-  return `WI-${String(max + 1).padStart(3, "0")}`;
+function deferConsent(dir) {
+  const p = join3(dir, ".kaddo", "telemetry-deferred.json");
+  writeFile2(p, JSON.stringify({ deferredUntil: Date.now() + DEFERRAL_DURATION_MS }));
 }
-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 matter17.stringify("\n" + body, data);
+function consentNotice() {
+  return '[Telemetry consent] Anonymous usage telemetry has not been configured.\n  Collects: command usage, version, lifecycle events.\n  Never collects: source code, knowledge, prompts or PII.\n  Use kaddo_set_telemetry_consent to enable, disable, or defer ("not-now").';
 }
-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}.`
-    );
+var TELEMETRY_DIR = ".kaddo/telemetry";
+var IDENTITY_FILE = "identity.json";
+function identityPath(dir) {
+  return join3(dir, TELEMETRY_DIR, IDENTITY_FILE);
+}
+function loadIdentity(dir) {
+  const p = identityPath(dir);
+  if (!exists2(p)) return null;
+  try {
+    return JSON.parse(readFile2(p));
+  } catch {
+    return null;
   }
-  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 } = matter17(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;
+}
+var TELEMETRY_DIR2 = ".kaddo/telemetry";
+var BUFFER_FILE = "buffer.json";
+function bufferPath(dir) {
+  return join3(dir, TELEMETRY_DIR2, BUFFER_FILE);
+}
+function readBuffer(dir) {
+  const p = bufferPath(dir);
+  if (!exists2(p)) return [];
+  try {
+    const data = JSON.parse(readFile2(p));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
   }
-  data.candidates = cands;
-  const newContent = matter17.stringify(content, data);
-  writeFile2(ini.filePath, newContent);
-  const updated = parseInitiative2(dir, ini.filePath, newContent);
-  if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
-  return { workItemId: wiId, fileName, initiative: updated };
+}
+function bufferSize(dir) {
+  return readBuffer(dir).length;
+}
+function getStatus(dir) {
+  const config = loadConfig2(dir);
+  const consent = getConsentState(config);
+  const enabled = consent === "enabled";
+  const identity = loadIdentity(dir);
+  return {
+    consent,
+    enabled,
+    registered: identity?.registered ?? false,
+    pendingEvents: enabled ? bufferSize(dir) : 0,
+    lastError: null
+  };
 }
 var SUCCESS_HEADING_RE = /^#{1,6}\s*(success criteria|criterios de[ét]xito|criterios de éxito)\s*$/i;
 var HEADING_RE2 = /^#{1,6}\s+/;
@@ -21843,7 +22367,7 @@ function evaluateInitiativeCompletion(dir, ini) {
 // ../cli/src/core/resource-write.ts
 import fs6 from "fs";
 import path5 from "path";
-import matter23 from "gray-matter";
+import matter24 from "gray-matter";
 var RESOURCES_DIR = "knowledge/tech/resources";
 var ResourceWriteError = class extends Error {
   constructor(code, message) {
@@ -21953,7 +22477,7 @@ function buildFrontmatter(id, input, base = {}) {
   return data;
 }
 function serialize(data, body) {
-  return matter23.stringify(`
+  return matter24.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -21993,7 +22517,7 @@ function updateResource(dir, id, input) {
     throw new ResourceWriteError("VALIDATION_FAILED", findings.filter((f3) => f3.level === "error").map((f3) => f3.message).join("; "));
   }
   const raw = readFile(match.filePath);
-  const parsed = matter23(raw);
+  const parsed = matter24(raw);
   const base = parsed.data ?? {};
   const data = buildFrontmatter(match.id || id, input, base);
   let body = parsed.content.trim();
@@ -22226,7 +22750,7 @@ var CANDIDATE_DISCOVERY_GUIDANCE2 = [
 // ../cli/src/core/deprecation-write.ts
 import fs7 from "fs";
 import path6 from "path";
-import matter24 from "gray-matter";
+import matter25 from "gray-matter";
 var DeprecationWriteError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -22244,14 +22768,14 @@ function atomicWrite2(filePath, content) {
   fs7.renameSync(tmp, filePath);
 }
 function serialize3(data, body) {
-  return matter24.stringify(`
+  return matter25.stringify(`
 ${body.trim()}
 `, data);
 }
 function allPlanArtifacts(dir) {
   return discoverKnowledge(dir).filter((a2) => a2.type === DEPRECATION_ARTIFACT_TYPE);
 }
-function nextPlanId(dir, explicit) {
+function nextPlanId2(dir, explicit) {
   if (explicit && explicit.trim()) return explicit.trim();
   let max = 0;
   for (const a2 of allPlanArtifacts(dir)) {
@@ -22310,7 +22834,7 @@ function validateTargetInput(dir, raw) {
 function loadPlanRaw(dir, planId) {
   const match = allPlanArtifacts(dir).find((a2) => a2.id === planId || a2.title === planId);
   if (!match) throw new DeprecationWriteError("NOT_FOUND", `Deprecation Plan "${planId}" not found.`);
-  const parsed = matter24(readFile(match.filePath));
+  const parsed = matter25(readFile(match.filePath));
   const data = { ...parsed.data ?? {} };
   return { filePath: match.filePath, data, body: parsed.content.trim() };
 }
@@ -22327,7 +22851,7 @@ function createPlan(dir, input) {
   if (existing.some((a2) => (a2.title || "").toLowerCase() === title.toLowerCase())) {
     throw new DeprecationWriteError("DUPLICATE", `A plan titled "${title}" already exists.`);
   }
-  const id = nextPlanId(dir, input.id);
+  const id = nextPlanId2(dir, input.id);
   const data = {
     type: DEPRECATION_ARTIFACT_TYPE,
     id,
@@ -22498,12 +23022,12 @@ function markWorkItemReady(root, id, confirm2) {
   }
   const raw = readText(root, item.path);
   if (!raw) return fail(`Could not read Work Item file: ${item.path}`);
-  const parsed = matter25(raw);
+  const parsed = matter26(raw);
   const data = { ...parsed.data };
   const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
   data.ready_at = today3;
-  const newContent = matter25.stringify(parsed.content, data);
+  const newContent = matter26.stringify(parsed.content, data);
   const posixPath = item.path.replace(/\\/g, "/");
   let newRelPath = item.path;
   if (posixPath.includes("/work-items/draft/")) {
@@ -22798,7 +23322,7 @@ function removeDeprecationTargetTool(root, planId, targetId, confirm2) {
 // src/multirepo.ts
 import fs8 from "fs";
 import path7 from "path";
-import matter26 from "gray-matter";
+import matter27 from "gray-matter";
 import { parse as parseYaml12, stringify as stringifyYaml8 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
@@ -22870,7 +23394,7 @@ function firstParagraph3(md) {
   }
   return "";
 }
-function slugify4(s) {
+function slugify5(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
 }
 function modulesListTool(root, args) {
@@ -22950,7 +23474,7 @@ function validateWorkItemModulesTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter26(raw);
+  const parsed = matter27(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -23003,7 +23527,7 @@ function getWorkItemContextTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter26(raw);
+  const parsed = matter27(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -23057,7 +23581,7 @@ function extractSection(content, heading) {
   return out;
 }
 function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
-  const slug7 = slugify4(wi.title);
+  const slug7 = slugify5(wi.title);
   const wiLower = wi.id.toLowerCase();
   const coreBranch = `feature/${wiLower}-${slug7}`;
   const moduleBranches = {};
@@ -23089,7 +23613,7 @@ function suggestBranchStrategyTool(root, args) {
   if (!wi) return fail2(`Work Item "${args.workItemId}" not found.`);
   const raw = readText(root, wi.path);
   if (!raw) return fail2(`Could not read Work Item file.`);
-  const parsed = matter26(raw);
+  const parsed = matter27(raw);
   const data = parsed.data;
   const affectedModules = Array.isArray(data.affected_modules) ? data.affected_modules.map(String) : [];
   const codeEntries = Array.isArray(data.code) ? data.code.filter((c) => typeof c === "object" && c !== null).map((c) => ({ repo: typeof c.repo === "string" ? c.repo : void 0, paths: Array.isArray(c.paths) ? c.paths.map(String) : [] })) : [];
@@ -23120,7 +23644,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 = `${slugify4(config.project?.name ?? "project")}-${args.module}`;
+      capsuleName = `${slugify5(config.project?.name ?? "project")}-${args.module}`;
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.project?.name ?? "unknown"}/${args.module}`,
@@ -23142,7 +23666,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 = slugify4(modId);
+      capsuleName = slugify5(modId);
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
@@ -23170,7 +23694,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 = `${slugify4(config.project?.name ?? "project")}-system`;
+    capsuleName = `${slugify5(config.project?.name ?? "project")}-system`;
     capsuleData = {
       type: "knowledge-capsule",
       system: config.project?.name ?? "unknown",
@@ -23191,7 +23715,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 = slugify4(modId);
+      capsuleName = slugify5(modId);
       capsuleData = {
         type: "knowledge-capsule",
         system: `${config.multirepo?.parent_system ?? "unknown"}/${modId}`,
@@ -23207,7 +23731,7 @@ function exportCapsuleTool(root, args) {
       };
     } else {
       capsuleType = "project";
-      capsuleName = slugify4(config.project?.name ?? "project");
+      capsuleName = slugify5(config.project?.name ?? "project");
       capsuleData = {
         type: "knowledge-capsule",
         system: config.project?.name ?? "unknown",
@@ -23370,7 +23894,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 strList3(v) {
+function strList4(v) {
   return Array.isArray(v) ? v.map((x2) => typeof x2 === "string" ? x2.trim() : "").filter(Boolean) : [];
 }
 function loadSystemTopology2(dir) {
@@ -23411,7 +23935,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 = strList3(rawImpl).filter((p) => {
+    const implementation = strList4(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;
@@ -23419,7 +23943,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 = strList3(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative2);
+    const evidence = strList4(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative2);
     seenIds.add(id);
     entities.push({
       id,
@@ -23428,7 +23952,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: strList3(e.knowledge ?? e.knowledge_refs),
+      knowledgeRefs: strList4(e.knowledge ?? e.knowledge_refs),
       ...provenance ? { provenance } : {},
       evidence
     });
@@ -23462,7 +23986,7 @@ function parseTopologyContent2(raw, dir) {
     }
     seenRels.add(key);
     const prov = r2.provenance;
-    relationships.push({ from, to, type, evidence: strList3(r2.evidence ?? prov?.evidence_refs).filter(isRelative2) });
+    relationships.push({ from, to, type, evidence: strList4(r2.evidence ?? prov?.evidence_refs).filter(isRelative2) });
   }
   return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
 }
@@ -23849,14 +24373,14 @@ function systemImpactCandidatesTool(root, args) {
 }
 
 // ../cli/src/services/integrations.ts
-import matter28 from "gray-matter";
+import matter29 from "gray-matter";
 import { parse as parseYaml14, stringify as stringifyYaml10 } from "yaml";
 
 // ../cli/src/core/work-item-write.ts
 import fs10 from "fs";
 import path9 from "path";
 import crypto4 from "crypto";
-import matter27 from "gray-matter";
+import matter28 from "gray-matter";
 var SECTION_ORDER2 = [
   "Actor",
   "Outcome",
@@ -24904,7 +25428,7 @@ async function integrationsWorkItemTool(root, args) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter29 from "gray-matter";
+import matter30 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR4 = "knowledge";
 function readScanJson(dir) {
@@ -24917,7 +25441,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph4(markdown) {
-  const body = matter29(markdown).content.trim();
+  const body = matter30(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -25900,7 +26424,7 @@ function renderUnderstand(plan) {
 
 // ../cli/src/core/knowledge-consolidation.ts
 import { createHash as createHash3 } from "crypto";
-import matter30 from "gray-matter";
+import matter31 from "gray-matter";
 var KNOWLEDGE7 = "knowledge";
 var CONSOLIDATION_CATEGORIES = [
   "knowledge_redundancy",
@@ -25910,12 +26434,12 @@ var CONSOLIDATION_CATEGORIES = [
   "potentially_outdated",
   "knowledge_organization"
 ];
-function toPosix8(p) {
+function toPosix9(p) {
   return p.replace(/\\/g, "/");
 }
 function relFromDir(dir, filePath) {
-  const d3 = toPosix8(dir).replace(/\/+$/, "");
-  const f3 = toPosix8(filePath);
+  const d3 = toPosix9(dir).replace(/\/+$/, "");
+  const f3 = toPosix9(filePath);
   return f3.startsWith(d3 + "/") ? f3.slice(d3.length + 1) : f3;
 }
 function sha256(content) {
@@ -26033,7 +26557,7 @@ function stableOpportunityId(category, sources) {
 function layerOf(a2) {
   const byType = layerForType(a2.type);
   if (byType) return byType;
-  const p = toPosix8(a2.filePath);
+  const p = toPosix9(a2.filePath);
   if (p.includes(`/${KNOWLEDGE7}/business/`)) return "Business";
   if (p.includes(`/${KNOWLEDGE7}/product/`)) return "Product";
   if (p.includes(`/${KNOWLEDGE7}/tech/`)) return "Tech";
@@ -26057,7 +26581,7 @@ function buildConsolidationPlan(dir, opts = {}) {
   const loaded = rawArtifacts.map((a2) => {
     let body = "";
     try {
-      body = matter30(readFile(a2.filePath)).content;
+      body = matter31(readFile(a2.filePath)).content;
     } catch {
       body = "";
     }
@@ -26311,14 +26835,14 @@ function describeScope(scope) {
   return `module:${scope.module}`;
 }
 function isWorkItem(la) {
-  return toPosix8(la.artifact.filePath).includes("/delivery/work-items/");
+  return toPosix9(la.artifact.filePath).includes("/delivery/work-items/");
 }
 function isCompletedWorkItem(la) {
-  const p = toPosix8(la.artifact.filePath);
+  const p = toPosix9(la.artifact.filePath);
   return p.includes("/delivery/work-items/completed/") || isWorkItem(la) && la.artifact.status === "completed";
 }
 function isScaffolding(la) {
-  const p = toPosix8(la.artifact.filePath);
+  const p = toPosix9(la.artifact.filePath);
   return p.includes(`/${KNOWLEDGE7}/agents/`) || p.includes(`/${KNOWLEDGE7}/skills/`) || p.includes(`/${KNOWLEDGE7}/external/`) || la.artifact.type === "knowledge-capsule";
 }
 var NON_KNOWLEDGE_DOC_TYPES = /* @__PURE__ */ new Set([
@@ -26386,7 +26910,7 @@ function decisionFileExists(dir, decisionId) {
 function hintInScope(hint, scoped) {
   if (scoped.length === 0) return false;
   return scoped.some(
-    (la) => la.artifact.id === hint.artifact_id || hint.path && toPosix8(la.artifact.filePath).endsWith(toPosix8(hint.path))
+    (la) => la.artifact.id === hint.artifact_id || hint.path && toPosix9(la.artifact.filePath).endsWith(toPosix9(hint.path))
   );
 }
 function relationshipOpportunityFromHint(hint) {
@@ -26770,6 +27294,104 @@ function completeInitiativeTool(root, args) {
   }
 }
 
+// src/planning.ts
+var ok6 = (data) => ({ ok: true, data });
+var fail5 = (message) => ({ ok: false, message });
+function previewOrApply2(confirm2, action, effect, apply) {
+  if (!confirm2) return ok6({ action, effect, instruction: "Call again with confirm=true to apply." });
+  try {
+    return ok6({ applied: true, result: apply() });
+  } catch (err) {
+    if (err instanceof DeliveryPlanningWriteError) return fail5(err.message);
+    throw err;
+  }
+}
+function listPlansTool(root) {
+  return ok6(discoverDeliveryPlans2(root).map((p) => {
+    const prog = computePlanProgress(root, p);
+    return { id: p.id, title: p.title, status: p.status, milestones: p.milestones.length, epics: prog.epics.total, delivery: prog.delivery };
+  }));
+}
+function getPlanTool(root, id) {
+  const plan = getPlan(root, id);
+  if (!plan) return fail5(`Plan ${id} not found.`);
+  return ok6({
+    id: plan.id,
+    title: plan.title,
+    status: plan.status,
+    objective: plan.objective,
+    milestones: plan.milestones,
+    dependsOn: plan.dependsOn,
+    successCriteria: plan.successCriteria,
+    risks: plan.risks,
+    references: plan.references,
+    epics: epicsInPlan(root, plan.id).map((e) => ({ id: e.id, title: e.title, status: e.status, milestone: e.milestone }))
+  });
+}
+function getPlanProgressTool(root, id) {
+  const plan = getPlan(root, id);
+  if (!plan) return fail5(`Plan ${id} not found.`);
+  return ok6(computePlanProgress(root, plan));
+}
+function listEpicsTool(root) {
+  return ok6(discoverEpics2(root).map((e) => {
+    const prog = computeEpicProgress(root, e);
+    return { id: e.id, title: e.title, status: e.status, plan: e.plan, milestone: e.milestone, delivery: prog.delivery };
+  }));
+}
+function getEpicTool(root, id) {
+  const epic = getEpic(root, id);
+  if (!epic) return fail5(`Epic ${id} not found.`);
+  return ok6({
+    id: epic.id,
+    title: epic.title,
+    status: epic.status,
+    outcome: epic.outcome,
+    plan: epic.plan,
+    milestone: epic.milestone,
+    dependsOn: epic.dependsOn,
+    successCriteria: epic.successCriteria,
+    relatedCapabilities: epic.relatedCapabilities,
+    initiatives: initiativesInEpic(root, epic.id).map((i) => ({ id: i.id, title: i.title, status: i.status, owners: i.owners, contributors: i.contributors })),
+    workItems: workItemsInEpic(root, epic.id).map((w3) => ({ id: w3.id, title: w3.title, status: w3.lifecycle }))
+  });
+}
+function getEpicProgressTool(root, id) {
+  const epic = getEpic(root, id);
+  if (!epic) return fail5(`Epic ${id} not found.`);
+  return ok6(computeEpicProgress(root, epic));
+}
+function validatePlanningTool(root) {
+  return ok6({ findings: validatePlanningGraph(root) });
+}
+function createPlanTool(root, args) {
+  if (!args.title?.trim()) return fail5("title is required.");
+  return previewOrApply2(
+    args.confirm,
+    "create-delivery-plan",
+    `A new Delivery Plan "${args.title.trim()}" will be created under knowledge/delivery/plans/.`,
+    () => createDeliveryPlan(root, { title: args.title, objective: args.objective })
+  );
+}
+function createEpicTool(root, args) {
+  if (!args.title?.trim()) return fail5("title is required.");
+  return previewOrApply2(
+    args.confirm,
+    "create-epic",
+    `A new Epic "${args.title.trim()}"${args.plan ? ` in ${args.plan}` : ""} will be created under knowledge/delivery/epics/.`,
+    () => createEpic(root, { title: args.title, plan: args.plan, milestone: args.milestone, outcome: args.outcome })
+  );
+}
+function associateInitiativeTool(root, args) {
+  if (!args.epic?.trim() || !args.initiative?.trim()) return fail5("epic and initiative are required.");
+  return previewOrApply2(
+    args.confirm,
+    "associate-initiative-epic",
+    `Initiative ${args.initiative} will be associated with Epic ${args.epic}.`,
+    () => associateInitiativeWithEpic(root, args.initiative, args.epic)
+  );
+}
+
 // src/server.ts
 var SERVER_NAME = "kaddo";
 var require2 = createRequire(import.meta.url);
@@ -27334,6 +27956,58 @@ function createServer(root) {
     { 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 PLANNING_READ_NOTE = "Read-only. Plans and Epics are an OPTIONAL planning layer; progress is derived from real Work Item state and never auto-completes.";
+  const PLANNING_WRITE_NOTE = "Without confirm=true returns a preview. With confirm=true applies the change. Writes only under knowledge/delivery/; never changes another element lifecycle, never infers responsibility from Git.";
+  server.registerTool(
+    "kaddo_list_plans",
+    { title: "List delivery plans", description: `List delivery plans with milestone count, epics and delivery progress. ${PLANNING_READ_NOTE}`, inputSchema: {} },
+    async () => toolText(guarded(root, () => listPlansTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_plan",
+    { title: "Get delivery plan", description: `Get one plan: objective, milestones, dependencies, success criteria and its epics. ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getPlanTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_get_plan_progress",
+    { title: "Get plan progress", description: `Planning coverage, delivery progress and completion readiness for a plan. ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getPlanProgressTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_list_epics",
+    { title: "List epics", description: `List epics with their plan/milestone and delivery progress. ${PLANNING_READ_NOTE}`, inputSchema: {} },
+    async () => toolText(guarded(root, () => listEpicsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_epic",
+    { title: "Get epic", description: `Get one epic: outcome, plan/milestone, dependencies, initiatives and work items (derived). ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getEpicTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_get_epic_progress",
+    { title: "Get epic progress", description: `Planning coverage, delivery progress and completion readiness for an epic. ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getEpicProgressTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_validate_planning",
+    { title: "Validate planning graph", description: `Deterministic validation: invalid references, dependency cycles, duplicate milestones and pending dependencies. ${PLANNING_READ_NOTE}`, inputSchema: {} },
+    async () => toolText(guarded(root, () => validatePlanningTool(root)))
+  );
+  server.registerTool(
+    "kaddo_create_plan",
+    { title: "Create delivery plan", description: `Create a new delivery plan. ${PLANNING_WRITE_NOTE}`, inputSchema: { title: z4.string(), objective: z4.string().optional(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => createPlanTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_create_epic",
+    { title: "Create epic", description: `Create a new epic, optionally in a plan/milestone (validated). ${PLANNING_WRITE_NOTE}`, inputSchema: { title: z4.string(), plan: z4.string().optional(), milestone: z4.string().optional(), outcome: z4.string().optional(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => createEpicTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_associate_initiative_epic",
+    { title: "Associate initiative with epic", description: `Associate an existing Initiative with an Epic (validated). ${PLANNING_WRITE_NOTE}`, inputSchema: { epic: z4.string(), initiative: z4.string(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => associateInitiativeTool(root, args)))
+  );
   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",