@kaddo/mcp 3.134.0 → 3.135.0

package/dist/index.js

@@ -2903,7 +2903,7 @@ ${items.map((i2) => `- ${i2}`).join("\n")}
 `;
 }
 function renderCapsuleMarkdown(c3) {
-  const fm = [
+  const fm2 = [
     "---",
     "type: knowledge-capsule",
     `system: ${c3.system}`,
@@ -2915,7 +2915,7 @@ function renderCapsuleMarkdown(c3) {
     "---"
   ].join("\n");
   const parts = [
-    fm,
+    fm2,
     "",
     `# ${c3.system} \u2014 Knowledge Capsule`,
     "",
@@ -3365,40 +3365,40 @@ function purposeFromBody(body) {
 }
 function toDetail(filePath, relPath, raw) {
   const parsed = matter7(raw);
-  const fm = parsed.data ?? {};
+  const fm2 = parsed.data ?? {};
   const body = parsed.content.trim();
-  const id = str(fm.id) ?? "";
+  const id = str(fm2.id) ?? "";
   return {
     id,
-    title: str(fm.title) ?? id,
-    resourceType: str(fm.resource_type),
-    provider: str(fm.provider),
-    environments: strArray(fm.environments),
-    scope: parseScope(fm.scope),
-    modules: strArray(fm.modules),
+    title: str(fm2.title) ?? id,
+    resourceType: str(fm2.resource_type),
+    provider: str(fm2.provider),
+    environments: strArray(fm2.environments),
+    scope: parseScope(fm2.scope),
+    modules: strArray(fm2.modules),
     path: relPath,
-    purpose: str(fm.purpose) ?? purposeFromBody(body),
-    interfaces: parseInterfaces(fm.access_interfaces),
-    boundaries: parseBoundaries(fm.access_boundaries),
+    purpose: str(fm2.purpose) ?? purposeFromBody(body),
+    interfaces: parseInterfaces(fm2.access_interfaces),
+    boundaries: parseBoundaries(fm2.access_boundaries),
     ...(() => {
-      const a3 = parseAuth(fm.authentication);
+      const a3 = parseAuth(fm2.authentication);
       return { authRefs: a3.refs, authMode: a3.mode };
     })(),
-    connectionProfiles: parseConnectionProfiles(fm.connection_profiles),
+    connectionProfiles: parseConnectionProfiles(fm2.connection_profiles),
     markdownBody: body
   };
 }
 function getResources(dir) {
   return discoverKnowledge(dir).filter((a3) => a3.type === RESOURCE_ARTIFACT_TYPE).map((a3) => {
-    const fm = a3.rawFrontmatter;
+    const fm2 = a3.rawFrontmatter;
     return {
-      id: a3.id || str(fm.id) || a3.title,
-      title: a3.title || str(fm.title) || a3.id,
-      resourceType: str(fm.resource_type),
-      provider: str(fm.provider),
-      environments: strArray(fm.environments),
-      scope: parseScope(fm.scope),
-      modules: strArray(fm.modules),
+      id: a3.id || str(fm2.id) || a3.title,
+      title: a3.title || str(fm2.title) || a3.id,
+      resourceType: str(fm2.resource_type),
+      provider: str(fm2.provider),
+      environments: strArray(fm2.environments),
+      scope: parseScope(fm2.scope),
+      modules: strArray(fm2.modules),
       path: a3.relPath
     };
   }).sort((x2, y) => x2.id.localeCompare(y.id));
@@ -3411,8 +3411,8 @@ function getResource(dir, id) {
   const raw = readFile(match.filePath);
   return toDetail(match.filePath, match.relPath, raw);
 }
-function parseWorkItemResources(fm) {
-  const v = fm.resources;
+function parseWorkItemResources(fm2) {
+  const v = fm2.resources;
   if (!Array.isArray(v)) return [];
   const out = [];
   for (const raw of v) {
@@ -3464,8 +3464,8 @@ var EVIDENCE_SIGNALS = [
 function str2(v) {
   return typeof v === "string" && v.trim() ? v.trim() : null;
 }
-function parseWorkItemDeprecationTargets(fm) {
-  const v = fm.deprecation_targets;
+function parseWorkItemDeprecationTargets(fm2) {
+  const v = fm2.deprecation_targets;
   if (!Array.isArray(v)) return [];
   const out = [];
   for (const raw of v) {
@@ -3599,13 +3599,13 @@ function purposeFromBody2(body) {
 }
 function getDeprecationPlans(dir) {
   return discoverKnowledge(dir).filter((a3) => a3.type === DEPRECATION_ARTIFACT_TYPE).map((a3) => {
-    const fm = a3.rawFrontmatter;
-    const targets = parseTargets(fm.targets);
+    const fm2 = a3.rawFrontmatter;
+    const targets = parseTargets(fm2.targets);
     return {
-      id: a3.id || str2(fm.id) || a3.title,
-      title: a3.title || str2(fm.title) || a3.id,
+      id: a3.id || str2(fm2.id) || a3.title,
+      title: a3.title || str2(fm2.title) || a3.id,
       path: a3.relPath,
-      status: str2(fm.status),
+      status: str2(fm2.status),
       targetCount: targets.length,
       lifecycleCounts: lifecycleCountsOf(targets)
     };
@@ -3618,17 +3618,17 @@ function getDeprecationPlan(dir, id) {
   if (!match) return null;
   const raw = readFile(match.filePath);
   const parsed = matter8(raw);
-  const fm = parsed.data ?? {};
+  const fm2 = parsed.data ?? {};
   const body = parsed.content.trim();
-  const targets = parseTargets(fm.targets);
+  const targets = parseTargets(fm2.targets);
   return {
-    id: str2(fm.id) ?? match.id,
-    title: str2(fm.title) ?? match.title,
+    id: str2(fm2.id) ?? match.id,
+    title: str2(fm2.title) ?? match.title,
     path: match.relPath,
-    status: str2(fm.status),
+    status: str2(fm2.status),
     targetCount: targets.length,
     lifecycleCounts: lifecycleCountsOf(targets),
-    purpose: str2(fm.purpose) ?? purposeFromBody2(body),
+    purpose: str2(fm2.purpose) ?? purposeFromBody2(body),
     targets,
     markdownBody: body
   };
@@ -4154,9 +4154,9 @@ var QUALITY_NOTE = {
   sparse: "The graph has many nodes but few meaningful edges.",
   empty: "The graph has almost no relationships."
 };
-function yamlBlock(fm) {
+function yamlBlock(fm2) {
   const lines = ["```yaml"];
-  for (const [k2, vals] of Object.entries(fm)) {
+  for (const [k2, vals] of Object.entries(fm2)) {
     lines.push(`${k2}:`);
     for (const v of vals) lines.push(`  - ${v}`);
   }
@@ -9348,7 +9348,7 @@ var AGENT_PROMPTS = [
 // ../cli/src/modules/agents.ts
 function withAgentFrontMatter(fileName, content) {
   const name = fileName.replace(/\.md$/, "");
-  const fm = [
+  const fm2 = [
     "---",
     "type: agent",
     `name: ${name}`,
@@ -9357,7 +9357,7 @@ function withAgentFrontMatter(fileName, content) {
     "---",
     ""
   ].join("\n");
-  return fm + content.replace(/^\s+/, "");
+  return fm2 + content.replace(/^\s+/, "");
 }
 var agentReadme = {
   path: "knowledge/agents/README.md",
@@ -10385,8 +10385,8 @@ function analyzeMetadataHealth(dir) {
         if (isFile(p) && entry.endsWith(".md")) {
           try {
             const raw = readFile(p);
-            const fm = matter12(raw).data;
-            if (fm.status === "done") {
+            const fm2 = matter12(raw).data;
+            if (fm2.status === "done") {
               const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
               findings.push({
                 file: rel,
@@ -10719,8 +10719,8 @@ function buildProjectExplanation(dir) {
       };
     }),
     implementationEvidence: workItemArtifacts.filter((a3) => a3.affectedModules.length > 0).map((a3) => {
-      const fm = a3.rawFrontmatter;
-      const evidence = fm.implementation_evidence;
+      const fm2 = a3.rawFrontmatter;
+      const evidence = fm2.implementation_evidence;
       const repos = evidence?.repositories ?? {};
       const repoEvidence = {};
       for (const [repoId, data] of Object.entries(repos)) {
@@ -10738,8 +10738,8 @@ function buildProjectExplanation(dir) {
         validationStatus: a3.validationStatus || historicalDefault,
         releaseStatus: a3.releaseStatus || "not-assessed",
         affectedModules: a3.affectedModules,
-        releaseGates: Array.isArray(fm.release_gates) ? fm.release_gates : [],
-        completionExceptions: Array.isArray(fm.completion_exceptions) ? fm.completion_exceptions : [],
+        releaseGates: Array.isArray(fm2.release_gates) ? fm2.release_gates : [],
+        completionExceptions: Array.isArray(fm2.completion_exceptions) ? fm2.completion_exceptions : [],
         repoEvidence
       };
     })
@@ -13025,6 +13025,7 @@ import { parse as parseYaml32 } from "yaml";
 import { parse as parseYaml52, stringify as stringifyYaml32 } from "yaml";
 import { parse as parseYaml42, stringify as stringifyYaml22 } from "yaml";
 import matter32 from "gray-matter";
+import { createHash as createHash3 } from "crypto";
 import matter42 from "gray-matter";
 import matter52 from "gray-matter";
 import matter62 from "gray-matter";
@@ -21579,6 +21580,18 @@ 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"];
+var PLAN_TRANSITIONS = {
+  draft: ["in-progress", "cancelled"],
+  "in-progress": ["completed", "cancelled"],
+  completed: [],
+  cancelled: []
+};
+var EPIC_TRANSITIONS = {
+  planned: ["in-progress", "cancelled"],
+  "in-progress": ["completed", "cancelled"],
+  completed: [],
+  cancelled: []
+};
 function toPosix32(p) {
   return p.replace(/\\/g, "/");
 }
@@ -21859,6 +21872,9 @@ function validatePlanningGraph(dir) {
     findings.push({ level: "warning", kind: "pending_dependency", subject: e.id, message: `Epic ${e.id} is blocked by unfinished dependency ${d3}.` });
   return findings;
 }
+function revisionOf(content) {
+  return createHash3("sha256").update(content, "utf8").digest("hex").slice(0, 16);
+}
 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;
@@ -21963,40 +21979,40 @@ function purposeFromBody3(body) {
 }
 function toDetail2(filePath, relPath, raw) {
   const parsed = matter52(raw);
-  const fm = parsed.data ?? {};
+  const fm2 = parsed.data ?? {};
   const body = parsed.content.trim();
-  const id = str3(fm.id) ?? "";
+  const id = str3(fm2.id) ?? "";
   return {
     id,
-    title: str3(fm.title) ?? id,
-    resourceType: str3(fm.resource_type),
-    provider: str3(fm.provider),
-    environments: strArray4(fm.environments),
-    scope: parseScope2(fm.scope),
-    modules: strArray4(fm.modules),
+    title: str3(fm2.title) ?? id,
+    resourceType: str3(fm2.resource_type),
+    provider: str3(fm2.provider),
+    environments: strArray4(fm2.environments),
+    scope: parseScope2(fm2.scope),
+    modules: strArray4(fm2.modules),
     path: relPath,
-    purpose: str3(fm.purpose) ?? purposeFromBody3(body),
-    interfaces: parseInterfaces2(fm.access_interfaces),
-    boundaries: parseBoundaries2(fm.access_boundaries),
+    purpose: str3(fm2.purpose) ?? purposeFromBody3(body),
+    interfaces: parseInterfaces2(fm2.access_interfaces),
+    boundaries: parseBoundaries2(fm2.access_boundaries),
     ...(() => {
-      const a3 = parseAuth2(fm.authentication);
+      const a3 = parseAuth2(fm2.authentication);
       return { authRefs: a3.refs, authMode: a3.mode };
     })(),
-    connectionProfiles: parseConnectionProfiles2(fm.connection_profiles),
+    connectionProfiles: parseConnectionProfiles2(fm2.connection_profiles),
     markdownBody: body
   };
 }
 function getResources2(dir) {
   return discoverKnowledge2(dir).filter((a3) => a3.type === RESOURCE_ARTIFACT_TYPE2).map((a3) => {
-    const fm = a3.rawFrontmatter;
+    const fm2 = a3.rawFrontmatter;
     return {
-      id: a3.id || str3(fm.id) || a3.title,
-      title: a3.title || str3(fm.title) || a3.id,
-      resourceType: str3(fm.resource_type),
-      provider: str3(fm.provider),
-      environments: strArray4(fm.environments),
-      scope: parseScope2(fm.scope),
-      modules: strArray4(fm.modules),
+      id: a3.id || str3(fm2.id) || a3.title,
+      title: a3.title || str3(fm2.title) || a3.id,
+      resourceType: str3(fm2.resource_type),
+      provider: str3(fm2.provider),
+      environments: strArray4(fm2.environments),
+      scope: parseScope2(fm2.scope),
+      modules: strArray4(fm2.modules),
       path: a3.relPath
     };
   }).sort((x2, y) => x2.id.localeCompare(y.id));
@@ -22009,8 +22025,8 @@ function getResource2(dir, id) {
   const raw = readFile2(match.filePath);
   return toDetail2(match.filePath, match.relPath, raw);
 }
-function parseWorkItemResources2(fm) {
-  const v = fm.resources;
+function parseWorkItemResources2(fm2) {
+  const v = fm2.resources;
   if (!Array.isArray(v)) return [];
   const out = [];
   for (const raw of v) {
@@ -22034,8 +22050,8 @@ var EVIDENCE_SIGNALS2 = [
 function str22(v) {
   return typeof v === "string" && v.trim() ? v.trim() : null;
 }
-function parseWorkItemDeprecationTargets2(fm) {
-  const v = fm.deprecation_targets;
+function parseWorkItemDeprecationTargets2(fm2) {
+  const v = fm2.deprecation_targets;
   if (!Array.isArray(v)) return [];
   const out = [];
   for (const raw of v) {
@@ -22160,13 +22176,13 @@ function purposeFromBody22(body) {
 }
 function getDeprecationPlans2(dir) {
   return discoverKnowledge2(dir).filter((a3) => a3.type === DEPRECATION_ARTIFACT_TYPE2).map((a3) => {
-    const fm = a3.rawFrontmatter;
-    const targets = parseTargets2(fm.targets);
+    const fm2 = a3.rawFrontmatter;
+    const targets = parseTargets2(fm2.targets);
     return {
-      id: a3.id || str22(fm.id) || a3.title,
-      title: a3.title || str22(fm.title) || a3.id,
+      id: a3.id || str22(fm2.id) || a3.title,
+      title: a3.title || str22(fm2.title) || a3.id,
       path: a3.relPath,
-      status: str22(fm.status),
+      status: str22(fm2.status),
       targetCount: targets.length,
       lifecycleCounts: lifecycleCountsOf2(targets)
     };
@@ -22179,17 +22195,17 @@ function getDeprecationPlan2(dir, id) {
   if (!match) return null;
   const raw = readFile2(match.filePath);
   const parsed = matter62(raw);
-  const fm = parsed.data ?? {};
+  const fm2 = parsed.data ?? {};
   const body = parsed.content.trim();
-  const targets = parseTargets2(fm.targets);
+  const targets = parseTargets2(fm2.targets);
   return {
-    id: str22(fm.id) ?? match.id,
-    title: str22(fm.title) ?? match.title,
+    id: str22(fm2.id) ?? match.id,
+    title: str22(fm2.title) ?? match.title,
     path: match.relPath,
-    status: str22(fm.status),
+    status: str22(fm2.status),
     targetCount: targets.length,
     lifecycleCounts: lifecycleCountsOf2(targets),
-    purpose: str22(fm.purpose) ?? purposeFromBody22(body),
+    purpose: str22(fm2.purpose) ?? purposeFromBody22(body),
     targets,
     markdownBody: body
   };
@@ -26206,7 +26222,7 @@ var AGENT_PROMPTS2 = [
 ].map((p) => ({ fileName: p.fileName, content: withResponsibilityTrace2(p.fileName, p.content) }));
 function withAgentFrontMatter2(fileName, content) {
   const name = fileName.replace(/\.md$/, "");
-  const fm = [
+  const fm2 = [
     "---",
     "type: agent",
     `name: ${name}`,
@@ -26215,7 +26231,7 @@ function withAgentFrontMatter2(fileName, content) {
     "---",
     ""
   ].join("\n");
-  return fm + content.replace(/^\s+/, "");
+  return fm2 + content.replace(/^\s+/, "");
 }
 var agentReadme2 = {
   path: "knowledge/agents/README.md",
@@ -26978,12 +26994,267 @@ function materializeCandidate(dir, id, candidateId) {
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
   return { workItemId: wiId, fileName, initiative: updated };
 }
+function normalizeCriterion(text22) {
+  return text22.trim().toLowerCase().replace(/\s+/g, " ");
+}
+var STATUSES = ["passed", "failed", "not-verified", "manual-review-required"];
+function optStr42(v) {
+  if (typeof v === "string" && v.trim()) return v.trim();
+  if (typeof v === "number") return String(v);
+  return void 0;
+}
+function parseEvidenceList(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const o3 = entry;
+    const criterion = optStr42(o3.criterion);
+    if (!criterion) continue;
+    const statusRaw = optStr42(o3.status);
+    const status = STATUSES.includes(statusRaw ?? "") ? statusRaw : "not-verified";
+    const method = optStr42(o3.method);
+    out.push({
+      criterion,
+      status,
+      ...optStr42(o3.evidence) ? { evidence: optStr42(o3.evidence) } : {},
+      ...optStr42(o3.reference) ? { reference: optStr42(o3.reference) } : {},
+      ...method === "automated" || method === "manual" ? { method } : {},
+      ...optStr42(o3.verified_at) ? { verified_at: optStr42(o3.verified_at) } : {},
+      ...optStr42(o3.verified_by) ? { verified_by: optStr42(o3.verified_by) } : {}
+    });
+  }
+  return out;
+}
+function parseExceptions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const o3 = entry;
+    const id = optStr42(o3.id);
+    if (!id) continue;
+    const st = optStr42(o3.status);
+    const status = st === "accepted" || st === "rejected" ? st : "proposed";
+    out.push({
+      id,
+      status,
+      ...optStr42(o3.criterion) ? { criterion: optStr42(o3.criterion) } : {},
+      ...optStr42(o3.reason) ? { reason: optStr42(o3.reason) } : {}
+    });
+  }
+  return out;
+}
+function buildOutcomeVerification(declared, evidence, exceptions = []) {
+  const byCriterion = /* @__PURE__ */ new Map();
+  for (const e of evidence) byCriterion.set(normalizeCriterion(e.criterion), e);
+  const declaredKeys = new Set(declared.map(normalizeCriterion));
+  const counts = /* @__PURE__ */ new Map();
+  for (const c3 of declared) counts.set(normalizeCriterion(c3), (counts.get(normalizeCriterion(c3)) ?? 0) + 1);
+  const ambiguousKeys = new Set([...counts.entries()].filter(([, n2]) => n2 > 1).map(([k2]) => k2));
+  const waived = new Set(
+    exceptions.filter((x2) => x2.status === "accepted" && x2.reason?.trim() && x2.criterion && declaredKeys.has(normalizeCriterion(x2.criterion)) && !ambiguousKeys.has(normalizeCriterion(x2.criterion))).map((x2) => normalizeCriterion(x2.criterion))
+  );
+  const criteria = declared.map((criterion) => {
+    const key = normalizeCriterion(criterion);
+    const ambiguous = ambiguousKeys.has(key);
+    const e = ambiguous ? void 0 : byCriterion.get(key);
+    return {
+      criterion,
+      status: e?.status ?? "not-verified",
+      ...e?.evidence ? { evidence: e.evidence } : {},
+      ...e?.reference ? { reference: e.reference } : {},
+      ...e?.method ? { method: e.method } : {},
+      ...e?.verified_at ? { verifiedAt: e.verified_at } : {},
+      ...e?.verified_by ? { verifiedBy: e.verified_by } : {},
+      ...!ambiguous && waived.has(key) ? { waived: true } : {},
+      ...ambiguous ? { ambiguous: true } : {}
+    };
+  });
+  const stale = evidence.filter((e) => !declaredKeys.has(normalizeCriterion(e.criterion)));
+  return {
+    total: criteria.length,
+    // An ambiguous criterion is never counted as passed/waived; it counts as unverified until disambiguated.
+    passed: criteria.filter((c3) => !c3.ambiguous && (c3.status === "passed" || c3.waived)).length,
+    failed: criteria.filter((c3) => !c3.ambiguous && c3.status === "failed" && !c3.waived).length,
+    notVerified: criteria.filter((c3) => c3.ambiguous || c3.status === "not-verified" && !c3.waived).length,
+    manualReview: criteria.filter((c3) => !c3.ambiguous && c3.status === "manual-review-required" && !c3.waived).length,
+    ambiguous: criteria.filter((c3) => c3.ambiguous).length,
+    criteria,
+    stale
+  };
+}
+function fm(entity, key) {
+  return entity.rawFrontmatter?.[key];
+}
+function epicOutcomeVerification(epic) {
+  return buildOutcomeVerification(
+    epic.successCriteria,
+    parseEvidenceList(fm(epic, "outcome_verifications")),
+    parseExceptions(fm(epic, "completion_exceptions"))
+  );
+}
+function planOutcomeVerification(plan) {
+  return buildOutcomeVerification(
+    plan.successCriteria,
+    parseEvidenceList(fm(plan, "outcome_verifications")),
+    parseExceptions(fm(plan, "completion_exceptions"))
+  );
+}
+function planMilestoneVerifications(plan) {
+  const rawMs = Array.isArray(fm(plan, "milestones")) ? fm(plan, "milestones") : [];
+  return plan.milestones.map((m2) => {
+    const rawEntry = rawMs.find((r2) => r2 && typeof r2 === "object" && optStr42(r2.id)?.toLowerCase() === m2.id.toLowerCase());
+    const evidence = parseEvidenceList(rawEntry?.exit_verifications);
+    return { id: m2.id, title: m2.title, outcome: buildOutcomeVerification(m2.exitCriteria, evidence) };
+  });
+}
+function decide(blockers, softBlocks, hasAcceptedExceptions) {
+  if (blockers.length > 0) return "BLOCKED";
+  if (softBlocks.length > 0) return "NEEDS_WORK";
+  return hasAcceptedExceptions ? "READY_WITH_EXCEPTIONS" : "READY_TO_COMPLETE";
+}
+function evaluateEpicCompletion(dir, epic) {
+  const prog = computeEpicProgress(dir, epic);
+  const exceptions = parseExceptions(fm(epic, "completion_exceptions"));
+  const outcome = epicOutcomeVerification(epic);
+  const blockers = [];
+  const softBlocks = [];
+  const reasons = [];
+  const warnings = [];
+  for (const d3 of prog.readiness.blockingDependencies) blockers.push(`Blocked by unfinished dependency ${d3}.`);
+  for (const f3 of integrityBlockers(dir, epic.id)) blockers.push(f3);
+  evaluateOutcomeInto(epic.outcome, true, outcome, blockers, softBlocks, reasons, warnings);
+  if (prog.delivery.total > 0 && prog.delivery.completed < prog.delivery.total) {
+    softBlocks.push("committed-work-incomplete");
+    reasons.push(`Committed work is incomplete (${prog.delivery.completed}/${prog.delivery.total} Work Items completed).`);
+  }
+  const readiness = decide(blockers, softBlocks, exceptions.some((x2) => x2.status === "accepted"));
+  pushReadinessReason(readiness, reasons);
+  return {
+    id: epic.id,
+    kind: "epic",
+    status: epic.status,
+    readiness,
+    reasons,
+    blockers,
+    warnings,
+    outcome,
+    delivery: { total: prog.delivery.total, completed: prog.delivery.completed, blocked: prog.delivery.blocked },
+    blockingDependencies: prog.readiness.blockingDependencies,
+    exceptions
+  };
+}
+function evaluatePlanCompletion(dir, plan) {
+  const prog = computePlanProgress(dir, plan);
+  const exceptions = parseExceptions(fm(plan, "completion_exceptions"));
+  const outcome = planOutcomeVerification(plan);
+  const milestones = planMilestoneVerifications(plan);
+  const epics = epicsInPlan(dir, plan.id).map((e) => ({ id: e.id, status: e.status }));
+  const blockers = [];
+  const softBlocks = [];
+  const reasons = [];
+  const warnings = [];
+  for (const d3 of prog.readiness.blockingDependencies) blockers.push(`Blocked by unfinished dependency ${d3}.`);
+  for (const f3 of integrityBlockers(dir, plan.id)) blockers.push(f3);
+  evaluateOutcomeInto(plan.objective, false, outcome, blockers, softBlocks, reasons, warnings);
+  if (!plan.objective) warnings.push("No objective is declared for this Plan (optional, but recommended for completion review).");
+  if (prog.delivery.total > 0 && prog.delivery.completed < prog.delivery.total) {
+    softBlocks.push("committed-work-incomplete");
+    reasons.push(`Committed work is incomplete (${prog.delivery.completed}/${prog.delivery.total} Work Items completed).`);
+  }
+  if (epics.length === 0 && prog.delivery.total === 0) {
+    softBlocks.push("no-committed-work");
+    reasons.push("No Epics and no committed Work Items \u2014 the Plan has no verifiable deliverables yet.");
+  }
+  const openEpics = epics.filter((e) => e.status !== "completed" && e.status !== "cancelled");
+  if (openEpics.length > 0) {
+    softBlocks.push("epics-open");
+    reasons.push(`${openEpics.length} Epic(s) not yet completed: ${openEpics.map((e) => e.id).join(", ")}.`);
+  }
+  for (const m2 of milestones) {
+    if (m2.outcome.failed > 0) {
+      blockers.push(`Milestone ${m2.id} has a failed exit criterion.`);
+    }
+    const pending = m2.outcome.notVerified + m2.outcome.manualReview;
+    if (pending > 0) {
+      softBlocks.push(`milestone-${m2.id}-pending`);
+      reasons.push(`Milestone ${m2.id}: ${pending} exit criterion(s) not verified.`);
+    }
+    if (m2.outcome.stale.length > 0) warnings.push(`Milestone ${m2.id} has stale exit-criteria evidence.`);
+  }
+  const readiness = decide(blockers, softBlocks, exceptions.some((x2) => x2.status === "accepted"));
+  pushReadinessReason(readiness, reasons);
+  return {
+    id: plan.id,
+    kind: "plan",
+    status: plan.status,
+    readiness,
+    reasons,
+    blockers,
+    warnings,
+    outcome,
+    delivery: { total: prog.delivery.total, completed: prog.delivery.completed, blocked: prog.delivery.blocked },
+    blockingDependencies: prog.readiness.blockingDependencies,
+    milestones,
+    epics,
+    exceptions
+  };
+}
+function integrityBlockers(dir, subjectId) {
+  return validatePlanningGraph(dir).filter((f3) => f3.level === "error" && f3.subject.toLowerCase() === subjectId.toLowerCase()).map((f3) => f3.message);
+}
+function evaluateOutcomeInto(declaredOutcome, requireDeclaredOutcome, outcome, blockers, softBlocks, reasons, warnings) {
+  if (requireDeclaredOutcome && !declaredOutcome) {
+    softBlocks.push("no-outcome");
+    reasons.push("No expected outcome is declared.");
+  }
+  if (outcome.total === 0) {
+    softBlocks.push("no-success-criteria");
+    reasons.push("No success criteria to verify \u2014 completion cannot be judged by outcome.");
+  }
+  if (outcome.ambiguous > 0) {
+    softBlocks.push("criteria-ambiguous");
+    reasons.push(`${outcome.ambiguous} success criterion(s) collide in text \u2014 rename to disambiguate before verifying.`);
+  }
+  if (outcome.failed > 0) {
+    softBlocks.push("criteria-failed");
+    reasons.push(`${outcome.failed} success criterion(s) failed verification.`);
+  }
+  const pending = outcome.notVerified + outcome.manualReview - outcome.ambiguous;
+  if (pending > 0) {
+    softBlocks.push("criteria-unverified");
+    reasons.push(`${pending} success criterion(s) not verified (no or insufficient evidence).`);
+  }
+  if (outcome.stale.length > 0) warnings.push(`${outcome.stale.length} evidence record(s) no longer match a declared criterion (stale).`);
+}
+function pushReadinessReason(readiness, reasons) {
+  if (readiness === "READY_TO_COMPLETE") reasons.unshift("All success criteria are verified and committed work is complete. Human approval is still required to close.");
+  else if (readiness === "READY_WITH_EXCEPTIONS") reasons.unshift("Remaining gaps are covered by accepted exceptions. Human approval is still required to close.");
+}
 var DeliveryPlanningWriteError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "DeliveryPlanningWriteError";
   }
 };
+var PlanningConflictError = class extends Error {
+  constructor(id, expectedRevision, actualRevision) {
+    super(`"${id}" was modified since it was loaded (expected revision ${expectedRevision}, found ${actualRevision}). Reload and try again.`);
+    this.id = id;
+    this.expectedRevision = expectedRevision;
+    this.actualRevision = actualRevision;
+    this.name = "PlanningConflictError";
+  }
+  id;
+  expectedRevision;
+  actualRevision;
+};
+function assertFreshRevision(id, currentContent, opts) {
+  if (!opts?.expectedRevision) return;
+  const actual = revisionOf(currentContent);
+  if (actual !== opts.expectedRevision) throw new PlanningConflictError(id, opts.expectedRevision, actual);
+}
 function slugify3(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "item";
 }
@@ -27044,6 +27315,163 @@ function associateInitiativeWithEpic(dir, initiativeId, epicId) {
   if (!getEpic(dir, epicId)) throw new DeliveryPlanningWriteError(`Epic ${epicId} does not exist.`);
   return updateInitiative(dir, ini.id, { epic: epicId });
 }
+function today22() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+var PlanningNotReadyError = class extends DeliveryPlanningWriteError {
+  constructor(evaluation) {
+    super(`${evaluation.kind === "plan" ? "Plan" : "Epic"} ${evaluation.id} is not ready to complete (${evaluation.readiness}).`);
+    this.evaluation = evaluation;
+    this.name = "PlanningNotReadyError";
+  }
+  evaluation;
+};
+function transitionDeliveryPlan(dir, id, to, opts) {
+  const plan = getPlan(dir, id);
+  if (!plan) throw new DeliveryPlanningWriteError(`Plan ${id} does not exist.`);
+  if (!PLAN_STATES2.includes(to)) throw new DeliveryPlanningWriteError(`Invalid plan status: ${to}.`);
+  if (to === "completed") throw new DeliveryPlanningWriteError(`Completing Plan ${id} requires evidence-based review \u2014 use completeDeliveryPlan.`);
+  const raw = readFile2(plan.filePath);
+  assertFreshRevision(plan.id, raw, opts);
+  if (plan.status === to) return plan;
+  if (!PLAN_TRANSITIONS[plan.status].includes(to)) throw new DeliveryPlanningWriteError(`Invalid transition ${plan.status} \u2192 ${to} for Plan ${id}.`);
+  const { data, content } = matter132(raw, {});
+  data.status = to;
+  if (to === "completed") data.completed_at = today22();
+  const newContent = matter132.stringify(content, data);
+  writeFile2(plan.filePath, newContent);
+  const updated = parseDeliveryPlan2(dir, plan.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Plan after transition.");
+  return updated;
+}
+function transitionEpic(dir, id, to, opts) {
+  const epic = getEpic(dir, id);
+  if (!epic) throw new DeliveryPlanningWriteError(`Epic ${id} does not exist.`);
+  if (!EPIC_STATES2.includes(to)) throw new DeliveryPlanningWriteError(`Invalid epic status: ${to}.`);
+  if (to === "completed") throw new DeliveryPlanningWriteError(`Completing Epic ${id} requires evidence-based review \u2014 use completeEpic.`);
+  const raw = readFile2(epic.filePath);
+  assertFreshRevision(epic.id, raw, opts);
+  if (epic.status === to) return epic;
+  if (!EPIC_TRANSITIONS[epic.status].includes(to)) throw new DeliveryPlanningWriteError(`Invalid transition ${epic.status} \u2192 ${to} for Epic ${id}.`);
+  const { data, content } = matter132(raw, {});
+  data.status = to;
+  if (to === "completed") data.completed_at = today22();
+  const newContent = matter132.stringify(content, data);
+  writeFile2(epic.filePath, newContent);
+  const updated = parseEpic2(dir, epic.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Epic after transition.");
+  return updated;
+}
+function assertCriterionDeclared(declared, criterion, kind) {
+  const key = normalizeCriterion(criterion);
+  const matches = declared.filter((c3) => normalizeCriterion(c3) === key).length;
+  if (matches === 0) throw new DeliveryPlanningWriteError(`"${criterion}" is not a declared ${kind} criterion.`);
+  if (matches > 1) throw new DeliveryPlanningWriteError(`"${criterion}" matches more than one declared ${kind} criterion \u2014 rename them to disambiguate before recording evidence.`);
+}
+function upsertEvidence(existing, input) {
+  const list22 = Array.isArray(existing) ? existing.filter((e) => e && typeof e === "object" && !Array.isArray(e)) : [];
+  const key = normalizeCriterion(input.criterion);
+  const kept = list22.filter((e) => normalizeCriterion(String(e.criterion ?? "")) !== key);
+  const obj = { criterion: input.criterion.trim(), status: input.status };
+  if (input.evidence?.trim()) obj.evidence = input.evidence.trim();
+  if (input.reference?.trim()) obj.reference = input.reference.trim();
+  if (input.method) obj.method = input.method;
+  obj.verified_at = today22();
+  if (input.verifiedBy?.trim()) obj.verified_by = input.verifiedBy.trim();
+  return [...kept, obj];
+}
+function recordEpicOutcomeVerification(dir, id, input, opts) {
+  const epic = getEpic(dir, id);
+  if (!epic) throw new DeliveryPlanningWriteError(`Epic ${id} does not exist.`);
+  assertCriterionDeclared(epic.successCriteria, input.criterion, "success");
+  const raw = readFile2(epic.filePath);
+  assertFreshRevision(epic.id, raw, opts);
+  const { data, content } = matter132(raw, {});
+  data.outcome_verifications = upsertEvidence(data.outcome_verifications, input);
+  const newContent = matter132.stringify(content, data);
+  writeFile2(epic.filePath, newContent);
+  const updated = parseEpic2(dir, epic.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Epic after recording evidence.");
+  return updated;
+}
+function recordPlanOutcomeVerification(dir, id, input, opts) {
+  const plan = getPlan(dir, id);
+  if (!plan) throw new DeliveryPlanningWriteError(`Plan ${id} does not exist.`);
+  assertCriterionDeclared(plan.successCriteria, input.criterion, "success");
+  const raw = readFile2(plan.filePath);
+  assertFreshRevision(plan.id, raw, opts);
+  const { data, content } = matter132(raw, {});
+  data.outcome_verifications = upsertEvidence(data.outcome_verifications, input);
+  const newContent = matter132.stringify(content, data);
+  writeFile2(plan.filePath, newContent);
+  const updated = parseDeliveryPlan2(dir, plan.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Plan after recording evidence.");
+  return updated;
+}
+function recordMilestoneExitVerification(dir, planId, milestoneId, input, opts) {
+  const plan = getPlan(dir, planId);
+  if (!plan) throw new DeliveryPlanningWriteError(`Plan ${planId} does not exist.`);
+  const milestone = plan.milestones.find((m2) => m2.id.toLowerCase() === milestoneId.toLowerCase());
+  if (!milestone) throw new DeliveryPlanningWriteError(`Milestone ${milestoneId} is not defined in ${planId}.`);
+  assertCriterionDeclared(milestone.exitCriteria, input.criterion, "exit");
+  const raw = readFile2(plan.filePath);
+  assertFreshRevision(plan.id, raw, opts);
+  const { data, content } = matter132(raw, {});
+  const rawMs = Array.isArray(data.milestones) ? data.milestones : [];
+  const entry = rawMs.find((m2) => m2 && typeof m2 === "object" && String(m2.id ?? "").toLowerCase() === milestoneId.toLowerCase());
+  if (!entry) throw new DeliveryPlanningWriteError(`Milestone ${milestoneId} entry not found in ${planId} frontmatter.`);
+  entry.exit_verifications = upsertEvidence(entry.exit_verifications, input);
+  data.milestones = rawMs;
+  const newContent = matter132.stringify(content, data);
+  writeFile2(plan.filePath, newContent);
+  const updated = parseDeliveryPlan2(dir, plan.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Plan after recording milestone evidence.");
+  return updated;
+}
+function completionDecisionRecord(evaluation, input) {
+  const rec = { readiness: evaluation.readiness, decided_at: today22(), reasons: evaluation.reasons };
+  if (input.decidedBy?.trim()) rec.decided_by = input.decidedBy.trim();
+  if (input.note?.trim()) rec.note = input.note.trim();
+  const acceptedExceptions = evaluation.exceptions.filter((x2) => x2.status === "accepted");
+  if (acceptedExceptions.length > 0) rec.exceptions = acceptedExceptions;
+  return rec;
+}
+function completeEpic(dir, id, input = {}, opts) {
+  const epic = getEpic(dir, id);
+  if (!epic) throw new DeliveryPlanningWriteError(`Epic ${id} does not exist.`);
+  const evaluation = evaluateEpicCompletion(dir, epic);
+  if (evaluation.readiness !== "READY_TO_COMPLETE" && evaluation.readiness !== "READY_WITH_EXCEPTIONS") throw new PlanningNotReadyError(evaluation);
+  if (!EPIC_TRANSITIONS[epic.status].includes("completed")) throw new DeliveryPlanningWriteError(`Epic ${id} cannot move from ${epic.status} to completed.`);
+  const raw = readFile2(epic.filePath);
+  assertFreshRevision(epic.id, raw, opts);
+  const { data, content } = matter132(raw, {});
+  data.status = "completed";
+  data.completed_at = today22();
+  data.completion_decision = completionDecisionRecord(evaluation, input);
+  const newContent = matter132.stringify(content, data);
+  writeFile2(epic.filePath, newContent);
+  const updated = parseEpic2(dir, epic.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Epic after completion.");
+  return updated;
+}
+function completeDeliveryPlan(dir, id, input = {}, opts) {
+  const plan = getPlan(dir, id);
+  if (!plan) throw new DeliveryPlanningWriteError(`Plan ${id} does not exist.`);
+  const evaluation = evaluatePlanCompletion(dir, plan);
+  if (evaluation.readiness !== "READY_TO_COMPLETE" && evaluation.readiness !== "READY_WITH_EXCEPTIONS") throw new PlanningNotReadyError(evaluation);
+  if (!PLAN_TRANSITIONS[plan.status].includes("completed")) throw new DeliveryPlanningWriteError(`Plan ${id} cannot move from ${plan.status} to completed.`);
+  const raw = readFile2(plan.filePath);
+  assertFreshRevision(plan.id, raw, opts);
+  const { data, content } = matter132(raw, {});
+  data.status = "completed";
+  data.completed_at = today22();
+  data.completion_decision = completionDecisionRecord(evaluation, input);
+  const newContent = matter132.stringify(content, data);
+  writeFile2(plan.filePath, newContent);
+  const updated = parseDeliveryPlan2(dir, plan.filePath, newContent);
+  if (!updated) throw new DeliveryPlanningWriteError("Failed to parse the Plan after completion.");
+  return updated;
+}
 var USER_FACING_KEYWORDS_EN = [
   "user",
   "visitor",
@@ -27356,7 +27784,7 @@ function getWorkItem(dir, workItemId) {
   const base = toListItem(match);
   const body = readBody(match.filePath);
   const sections = splitSections(body);
-  const fm = match.rawFrontmatter;
+  const fm2 = match.rawFrontmatter;
   const knowledge = discoverKnowledge2(dir).filter((a3) => !a3.isWorkItem);
   const knowledgeById = new Map(knowledge.filter((k2) => k2.id).map((k2) => [k2.id, k2]));
   const detail = {
@@ -27373,21 +27801,21 @@ function getWorkItem(dir, workItemId) {
     moduleCoverage: normalizeCoverage(match.moduleCoverage),
     impactAnalysis: normalizeImpact(match.impactAnalysis),
     acceptanceCriteria: parseAcceptanceCriteria(sections),
-    implementationEvidence: parseEvidence(fm),
-    releaseGates: parseReleaseGates(fm),
-    completionExceptions: parseExceptions(fm),
+    implementationEvidence: parseEvidence(fm2),
+    releaseGates: parseReleaseGates(fm2),
+    completionExceptions: parseExceptions2(fm2),
     decisions: parseDecisions(match.decisions, knowledgeById),
-    relatedKnowledge: parseRelatedKnowledge(fm, knowledgeById),
-    source: parseWorkItemSource2(fm),
-    originalSnapshot: parseOriginalSnapshot(fm),
+    relatedKnowledge: parseRelatedKnowledge(fm2, knowledgeById),
+    source: parseWorkItemSource2(fm2),
+    originalSnapshot: parseOriginalSnapshot(fm2),
     path: match.relPath,
     // Faithful source of truth: the artifact body already read above, not reconstructed (WI-025).
     markdownBody: body.trim(),
     // External systems this WI relates to (WI-030), separate from affectedModules (code).
-    resources: parseWorkItemResources2(fm),
+    resources: parseWorkItemResources2(fm2),
     // Deprecation Targets this WI retires (WI-050), referenced not copied.
-    deprecationTargets: parseWorkItemDeprecationTargets2(fm),
-    ...parseSystemImpact(dir, fm)
+    deprecationTargets: parseWorkItemDeprecationTargets2(fm2),
+    ...parseSystemImpact(dir, fm2)
   };
   return { ...detail, refinement: computeRefinementStatus(detail) };
 }
@@ -27410,14 +27838,14 @@ function parseExplain(o3) {
 function emptyExplain() {
   return { reason: null, graphReason: null, evidenceRefs: [], evidenceSummary: null };
 }
-function parseSystemImpact(dir, fm) {
+function parseSystemImpact(dir, fm2) {
   const topology = loadSystemTopology(dir);
   const byId = new Map(topology.entities.map((e) => [e.id, e]));
   const resolve = (id) => {
     const e = byId.get(id);
     return { id, nodeId: `sys:${id}`, label: e?.label ?? id, kind: e?.kind ?? "unknown", moduleId: e?.moduleId ?? null };
   };
-  const affected = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map((raw) => {
+  const affected = Array.isArray(fm2.affected_system_entities) ? fm2.affected_system_entities.map((raw) => {
     if (typeof raw === "string") return raw ? { ...resolve(raw), ...emptyExplain() } : null;
     if (raw && typeof raw === "object") {
       const o3 = raw;
@@ -27426,13 +27854,13 @@ function parseSystemImpact(dir, fm) {
     }
     return null;
   }).filter((e) => e != null) : [];
-  const reviewed = Array.isArray(fm.reviewed_system_entities) ? fm.reviewed_system_entities.filter((r2) => Boolean(r2) && typeof r2 === "object").map((r2) => ({ ...resolve(String(r2.id ?? "")), ...parseExplain(r2), status: String(r2.status ?? "unknown") })).filter((r2) => r2.id) : [];
-  const graphRevision = typeof fm.graph_revision === "string" && fm.graph_revision.trim() ? fm.graph_revision.trim() : null;
+  const reviewed = Array.isArray(fm2.reviewed_system_entities) ? fm2.reviewed_system_entities.filter((r2) => Boolean(r2) && typeof r2 === "object").map((r2) => ({ ...resolve(String(r2.id ?? "")), ...parseExplain(r2), status: String(r2.status ?? "unknown") })).filter((r2) => r2.id) : [];
+  const graphRevision = typeof fm2.graph_revision === "string" && fm2.graph_revision.trim() ? fm2.graph_revision.trim() : null;
   const graphCoverage = topology.entities.length === 0 ? "unavailable" : topology.relationships.length > 0 ? "available" : "partial";
   return { affectedSystemEntities: affected, reviewedSystemEntities: reviewed, graphRevision, graphCoverage };
 }
-function parseOriginalSnapshot(fm) {
-  const raw = fm.original_snapshot;
+function parseOriginalSnapshot(fm2) {
+  const raw = fm2.original_snapshot;
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
   const o3 = raw;
   const title = typeof o3.title === "string" ? o3.title : void 0;
@@ -27535,12 +27963,12 @@ function normalizeImpact(ia) {
     ...v.question ? { question: v.question } : {}
   }));
 }
-function optStr42(v) {
+function optStr52(v) {
   if (typeof v === "string" && v.trim()) return v.trim();
   return void 0;
 }
-function parseEvidence(fm) {
-  const evidence = fm.implementation_evidence;
+function parseEvidence(fm2) {
+  const evidence = fm2.implementation_evidence;
   const repos = evidence?.repositories;
   if (!repos || typeof repos !== "object" || Array.isArray(repos)) return [];
   const out = [];
@@ -27550,13 +27978,13 @@ function parseEvidence(fm) {
     const validations = Array.isArray(d3.validations) ? d3.validations.map((v) => ({
       command: String(v.command ?? ""),
       status: String(v.status ?? "unknown"),
-      ...optStr42(v.reason) ? { reason: optStr42(v.reason) } : {}
+      ...optStr52(v.reason) ? { reason: optStr52(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"),
-      ...optStr42(m2.reason) ? { reason: optStr42(m2.reason) } : {}
+      ...optStr52(m2.reason) ? { reason: optStr52(m2.reason) } : {}
     })) : [];
     out.push({
       module,
@@ -27569,23 +27997,23 @@ function parseEvidence(fm) {
   }
   return out;
 }
-function parseReleaseGates(fm) {
-  if (!Array.isArray(fm.release_gates)) return [];
-  return fm.release_gates.filter((g) => g && typeof g === "object").map((g) => ({
+function parseReleaseGates(fm2) {
+  if (!Array.isArray(fm2.release_gates)) return [];
+  return fm2.release_gates.filter((g) => g && typeof g === "object").map((g) => ({
     id: String(g.id ?? ""),
     status: String(g.status ?? "pending"),
-    ...optStr42(g.reason) ? { reason: optStr42(g.reason) } : {},
-    ...optStr42(g.required_for) ? { requiredFor: optStr42(g.required_for) } : {}
+    ...optStr52(g.reason) ? { reason: optStr52(g.reason) } : {},
+    ...optStr52(g.required_for) ? { requiredFor: optStr52(g.required_for) } : {}
   }));
 }
-function parseExceptions(fm) {
-  if (!Array.isArray(fm.completion_exceptions)) return [];
-  return fm.completion_exceptions.filter((e) => e && typeof e === "object").map((e) => ({
+function parseExceptions2(fm2) {
+  if (!Array.isArray(fm2.completion_exceptions)) return [];
+  return fm2.completion_exceptions.filter((e) => e && typeof e === "object").map((e) => ({
     id: String(e.id ?? ""),
     status: String(e.status ?? "proposed"),
-    ...optStr42(e.reason) ? { reason: optStr42(e.reason) } : {},
-    ...optStr42(e.category) ? { category: optStr42(e.category) } : {},
-    ...optStr42(e.impact) ? { impact: optStr42(e.impact) } : {}
+    ...optStr52(e.reason) ? { reason: optStr52(e.reason) } : {},
+    ...optStr52(e.category) ? { category: optStr52(e.category) } : {},
+    ...optStr52(e.impact) ? { impact: optStr52(e.impact) } : {}
   }));
 }
 function parseDecisions(decisions, knowledgeById) {
@@ -27598,10 +28026,10 @@ function parseDecisions(decisions, knowledgeById) {
     };
   });
 }
-function parseRelatedKnowledge(fm, knowledgeById) {
+function parseRelatedKnowledge(fm2, knowledgeById) {
   const refs = /* @__PURE__ */ new Set();
   for (const field of ["related_knowledge", "knowledge", "related"]) {
-    const v = fm[field];
+    const v = fm2[field];
     if (Array.isArray(v)) {
       for (const r2 of v) if (typeof r2 === "string" && r2.trim()) refs.add(r2.trim());
     }
@@ -27769,7 +28197,7 @@ function createWorkItem(dir, opts) {
   if (!type) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${opts.type}".`);
   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 today3 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = opts.summary?.trim() || intent;
   const source22 = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
   const data = {
@@ -27778,7 +28206,7 @@ function createWorkItem(dir, opts) {
     title,
     status: "draft",
     work_type: type,
-    created_at: today22,
+    created_at: today3,
     source: source22,
     generated_by: "kaddo-admin",
     affected_modules: [],
@@ -28469,11 +28897,11 @@ function verifyWorkItem(dir, workItemId, input) {
   const artifacts = discoverWorkItems2(dir);
   const match = artifacts.find((a3) => (a3.id || a3.title) === workItemId);
   const lifecycle = lifecycleStateOf2({ status: match.status, filePath: match.filePath });
-  const fm = match.rawFrontmatter;
+  const fm2 = match.rawFrontmatter;
   const acVerifications = mapACVerifications(input.acVerifications);
   const acSummary = computeACSummary(acVerifications);
-  const releaseGates = Array.isArray(fm.release_gates) ? fm.release_gates : [];
-  const completionExceptions = Array.isArray(fm.completion_exceptions) ? fm.completion_exceptions : [];
+  const releaseGates = Array.isArray(fm2.release_gates) ? fm2.release_gates : [];
+  const completionExceptions = Array.isArray(fm2.completion_exceptions) ? fm2.completion_exceptions : [];
   const plannedVsActual = computePlannedVsActual(match.affectedModules, input.repos);
   const registeredModuleIds = loadMappedModules2(dir).map((m2) => m2.id);
   const modifiedRepoIds = input.repos.map((r2) => r2.repoId);
@@ -28484,7 +28912,7 @@ function verifyWorkItem(dir, workItemId, input) {
     validationStatus: match.validationStatus || "not-started",
     releaseStatus: match.releaseStatus || "not-assessed",
     affectedModules: match.affectedModules,
-    rawFrontmatter: fm,
+    rawFrontmatter: fm2,
     registeredModuleIds,
     modifiedRepoIds
   });
@@ -31264,10 +31692,10 @@ function modulesDiscoverTool(root, args) {
   return ok2({ discovered, applied: false });
 }
 function renderCapsuleMd(data) {
-  const fm = ["---", `type: knowledge-capsule`, `system: ${data.system}`, `version: ${data.version}`, `updated_at: ${data.updated_at}`, "---", ""].join("\n");
+  const fm2 = ["---", `type: knowledge-capsule`, `system: ${data.system}`, `version: ${data.version}`, `updated_at: ${data.updated_at}`, "---", ""].join("\n");
   const list3 = (items) => items.length === 0 ? "_To be completed._" : items.map((i2) => `- ${i2}`).join("\n");
   return [
-    fm,
+    fm2,
     `# ${data.system} \u2014 Knowledge Capsule
 `,
     `## Purpose
@@ -33867,7 +34295,7 @@ function renderUnderstand(plan) {
 }
 
 // ../cli/src/core/knowledge-consolidation.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import matter31 from "gray-matter";
 var KNOWLEDGE7 = "knowledge";
 var CONSOLIDATION_CATEGORIES = [
@@ -33887,7 +34315,7 @@ function relFromDir(dir, filePath) {
   return f3.startsWith(d3 + "/") ? f3.slice(d3.length + 1) : f3;
 }
 function sha256(content) {
-  return createHash3("sha256").update(content, "utf-8").digest("hex");
+  return createHash4("sha256").update(content, "utf-8").digest("hex");
 }
 var SHINGLE_SIZE = 6;
 var MIN_SHARED_RUN = 6;
@@ -34739,6 +35167,14 @@ function completeInitiativeTool(root, args) {
 }
 
 // src/planning.ts
+var EVIDENCE_STATUSES = ["passed", "failed", "not-verified", "manual-review-required"];
+function toEvidence(a3) {
+  if (!a3.criterion?.trim()) return "criterion is required.";
+  const status = a3.status ?? "passed";
+  if (!EVIDENCE_STATUSES.includes(status)) return `status must be one of: ${EVIDENCE_STATUSES.join(", ")}.`;
+  const method = a3.method === "automated" || a3.method === "manual" ? a3.method : void 0;
+  return { criterion: a3.criterion.trim(), status, evidence: a3.evidence, reference: a3.reference, method, verifiedBy: a3.verifiedBy };
+}
 var ok6 = (data) => ({ ok: true, data });
 var fail5 = (message) => ({ ok: false, message });
 function previewOrApply2(confirm2, action, effect, apply) {
@@ -34835,6 +35271,82 @@ function associateInitiativeTool(root, args) {
     () => associateInitiativeWithEpic(root, args.initiative, args.epic)
   );
 }
+function verifyPlanTool(root, id) {
+  const plan = getPlan(root, id);
+  if (!plan) return fail5(`Plan ${id} not found.`);
+  return ok6(evaluatePlanCompletion(root, plan));
+}
+function verifyEpicTool(root, id) {
+  const epic = getEpic(root, id);
+  if (!epic) return fail5(`Epic ${id} not found.`);
+  return ok6(evaluateEpicCompletion(root, epic));
+}
+function recordPlanEvidenceTool(root, args) {
+  const input = toEvidence(args);
+  if (typeof input === "string") return fail5(input);
+  const target = args.milestone ? `milestone ${args.milestone}` : "Plan outcome";
+  return previewOrApply2(
+    args.confirm,
+    "record-plan-evidence",
+    `Evidence [${input.status}] for ${target} criterion "${input.criterion}" on ${args.id} will be recorded.`,
+    () => args.milestone ? recordMilestoneExitVerification(root, args.id, args.milestone, input) : recordPlanOutcomeVerification(root, args.id, input)
+  );
+}
+function recordEpicEvidenceTool(root, args) {
+  const input = toEvidence(args);
+  if (typeof input === "string") return fail5(input);
+  return previewOrApply2(
+    args.confirm,
+    "record-epic-evidence",
+    `Evidence [${input.status}] for Epic outcome criterion "${input.criterion}" on ${args.id} will be recorded.`,
+    () => recordEpicOutcomeVerification(root, args.id, input)
+  );
+}
+function transitionPlanTool(root, args) {
+  if (args.to === "completed") return fail5("Use complete_plan for an evidence-based completion.");
+  return previewOrApply2(
+    args.confirm,
+    "transition-plan",
+    `Plan ${args.id} will transition to ${args.to}.`,
+    () => transitionDeliveryPlan(root, args.id, args.to)
+  );
+}
+function transitionEpicTool(root, args) {
+  if (args.to === "completed") return fail5("Use complete_epic for an evidence-based completion.");
+  return previewOrApply2(
+    args.confirm,
+    "transition-epic",
+    `Epic ${args.id} will transition to ${args.to}.`,
+    () => transitionEpic(root, args.id, args.to)
+  );
+}
+var APPROVAL_NOTE = "confirm=true is a confirmation step, not by itself proof of human approval \u2014 only complete with genuine human authorization.";
+function completePlanTool(root, args) {
+  const plan = getPlan(root, args.id);
+  if (!plan) return fail5(`Plan ${args.id} not found.`);
+  const evaluation = evaluatePlanCompletion(root, plan);
+  const ready = evaluation.readiness === "READY_TO_COMPLETE" || evaluation.readiness === "READY_WITH_EXCEPTIONS";
+  if (!args.confirm) return ok6({ action: "complete-plan", readiness: evaluation.readiness, evaluation, note: APPROVAL_NOTE, instruction: ready ? "Review the evaluation; call again with confirm=true to record the human completion decision." : `Not ready (${evaluation.readiness}). Resolve the blockers first.` });
+  try {
+    return ok6({ applied: true, result: completeDeliveryPlan(root, args.id, { decidedBy: args.decidedBy }) });
+  } catch (err) {
+    if (err instanceof PlanningNotReadyError || err instanceof DeliveryPlanningWriteError) return fail5(err.message);
+    throw err;
+  }
+}
+function completeEpicTool(root, args) {
+  const epic = getEpic(root, args.id);
+  if (!epic) return fail5(`Epic ${args.id} not found.`);
+  const evaluation = evaluateEpicCompletion(root, epic);
+  const ready = evaluation.readiness === "READY_TO_COMPLETE" || evaluation.readiness === "READY_WITH_EXCEPTIONS";
+  if (!args.confirm) return ok6({ action: "complete-epic", readiness: evaluation.readiness, evaluation, note: APPROVAL_NOTE, instruction: ready ? "Review the evaluation; call again with confirm=true to record the human completion decision." : `Not ready (${evaluation.readiness}). Resolve the blockers first.` });
+  try {
+    return ok6({ applied: true, result: completeEpic(root, args.id, { decidedBy: args.decidedBy }) });
+  } catch (err) {
+    if (err instanceof PlanningNotReadyError || err instanceof DeliveryPlanningWriteError) return fail5(err.message);
+    throw err;
+  }
+}
 
 // src/collaboration.ts
 async function getWorkItemCollaborationTool(root, id) {
@@ -35487,6 +35999,47 @@ function createServer(root) {
     { 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 EVIDENCE_IN = { id: z4.string(), criterion: z4.string(), status: z4.string().optional(), evidence: z4.string().optional(), reference: z4.string().optional(), method: z4.string().optional(), verifiedBy: z4.string().optional(), confirm: z4.boolean().optional() };
+  server.registerTool(
+    "kaddo_verify_plan",
+    { title: "Verify plan outcome", description: `Evidence-based completion readiness of a Plan: success criteria, milestone exit criteria, dependencies and reasons. ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => verifyPlanTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_verify_epic",
+    { title: "Verify epic outcome", description: `Evidence-based completion readiness of an Epic: success criteria, delivery, dependencies and reasons. ${PLANNING_READ_NOTE}`, inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => verifyEpicTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_record_plan_evidence",
+    { title: "Record plan evidence", description: `Record outcome (or milestone exit) verification evidence for one declared criterion. ${PLANNING_WRITE_NOTE}`, inputSchema: { ...EVIDENCE_IN, milestone: z4.string().optional() } },
+    async (args) => toolText(guarded(root, () => recordPlanEvidenceTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_record_epic_evidence",
+    { title: "Record epic evidence", description: `Record outcome verification evidence for one declared success criterion. ${PLANNING_WRITE_NOTE}`, inputSchema: EVIDENCE_IN },
+    async (args) => toolText(guarded(root, () => recordEpicEvidenceTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_transition_plan",
+    { title: "Transition plan", description: `Transition a Delivery Plan (start/cancel). Completion uses kaddo_complete_plan. ${PLANNING_WRITE_NOTE}`, inputSchema: { id: z4.string(), to: z4.string(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => transitionPlanTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_transition_epic",
+    { title: "Transition epic", description: `Transition an Epic (start/cancel). Completion uses kaddo_complete_epic. ${PLANNING_WRITE_NOTE}`, inputSchema: { id: z4.string(), to: z4.string(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => transitionEpicTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_complete_plan",
+    { title: "Complete plan", description: `Review readiness, then (confirm=true) record a human completion decision for a Plan. Never completes automatically; confirm is not itself proof of human approval. ${PLANNING_WRITE_NOTE}`, inputSchema: { id: z4.string(), decidedBy: z4.string().optional(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => completePlanTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_complete_epic",
+    { title: "Complete epic", description: `Review readiness, then (confirm=true) record a human completion decision for an Epic. Never completes automatically; confirm is not itself proof of human approval. ${PLANNING_WRITE_NOTE}`, inputSchema: { id: z4.string(), decidedBy: z4.string().optional(), confirm: z4.boolean().optional() } },
+    async (args) => toolText(guarded(root, () => completeEpicTool(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",

package/package.json

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