@kaddo/mcp 3.120.0 → 3.121.1

package/dist/index.js

@@ -389,7 +389,7 @@ function join(...parts) {
 }
 
 // ../cli/src/core/impact-report.ts
-import matter11 from "gray-matter";
+import matter12 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
@@ -499,8 +499,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path9 = i.path.join(".");
-      return path9 ? `  - ${path9}: ${i.message}` : `  - ${i.message}`;
+      const path10 = i.path.join(".");
+      return path10 ? `  - ${path10}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -941,11 +941,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path9 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path9)) return [];
+  const path10 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path10)) return [];
   let parsed;
   try {
-    parsed = parseYaml4(readFile(path9));
+    parsed = parseYaml4(readFile(path10));
   } catch {
     return [];
   }
@@ -2452,7 +2452,7 @@ function sectionParagraph2(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path9, md) {
+function parseCapsule(id, path10, md) {
   const { data } = matter4(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -2462,7 +2462,7 @@ function parseCapsule(id, path9, md) {
   }
   return {
     id,
-    path: path9,
+    path: path10,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -2735,6 +2735,252 @@ function parseWorkItemResources(fm) {
   return out;
 }
 
+// ../cli/src/core/deprecation.ts
+import matter7 from "gray-matter";
+var DEPRECATION_ARTIFACT_TYPE = "deprecation-plan";
+var DEPRECATION_PLANS_DIR = "knowledge/legacy/deprecations";
+var TARGET_TYPES = [
+  "module",
+  "route",
+  "function",
+  "ui",
+  "job",
+  "database-object",
+  "integration",
+  "config",
+  "other"
+];
+var LIFECYCLE_STATES2 = [
+  "candidate",
+  "usage-validated",
+  "soft-deprecated",
+  "disabled",
+  "removed-devtest",
+  "production-ready",
+  "production-changed",
+  "observing",
+  "completed",
+  "deprecated-retained"
+];
+var ENVIRONMENTS = ["development", "test", "production"];
+var ENVIRONMENT_STATES = ["active", "soft-deprecated", "disabled", "removed"];
+var EVIDENCE_SIGNALS = [
+  "static",
+  "runtime",
+  "database",
+  "external_consumers",
+  "human_review"
+];
+function str2(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function parseWorkItemDeprecationTargets(fm) {
+  const v = fm.deprecation_targets;
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (typeof raw === "string") {
+      const s = raw.trim();
+      if (!s) continue;
+      const slash = s.indexOf("/");
+      if (slash > 0) out.push({ plan: s.slice(0, slash).trim(), target: s.slice(slash + 1).trim() });
+      else out.push({ plan: null, target: s });
+      continue;
+    }
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const o2 = raw;
+      const target = str2(o2.target) ?? str2(o2.id);
+      if (!target) continue;
+      out.push({ plan: str2(o2.plan), target });
+    }
+  }
+  return out;
+}
+function strArray2(v) {
+  if (Array.isArray(v)) return v.map((x2) => String(x2).trim()).filter(Boolean);
+  if (typeof v === "string" && v.trim()) return [v.trim()];
+  return [];
+}
+function isValidTargetType(t) {
+  return TARGET_TYPES.includes(t);
+}
+function isValidLifecycleState(s) {
+  return LIFECYCLE_STATES2.includes(s);
+}
+function isValidEnvironmentState(s) {
+  return ENVIRONMENT_STATES.includes(s);
+}
+function parseAssessment(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    return { unusedConfidence: null, blastRadius: null, reversibility: null };
+  }
+  const o2 = v;
+  return {
+    unusedConfidence: str2(o2.unused_confidence),
+    blastRadius: str2(o2.blast_radius),
+    reversibility: str2(o2.reversibility)
+  };
+}
+function parseUsageEvidence(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const signal of EVIDENCE_SIGNALS) {
+    const raw = v[signal];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o2 = raw;
+    out[signal] = {
+      status: str2(o2.status) ?? "unknown",
+      quality: str2(o2.quality) ?? "unknown",
+      detail: str2(o2.detail)
+    };
+  }
+  return out;
+}
+function parseSoftDeprecation(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  const o2 = v;
+  const windowRaw = o2.observation_window_days;
+  const window = typeof windowRaw === "number" && Number.isFinite(windowRaw) && windowRaw >= 0 ? Math.floor(windowRaw) : null;
+  const exitCriteria = Array.isArray(o2.exit_criteria) ? o2.exit_criteria.map((c) => {
+    if (typeof c === "string") return c.trim() ? { description: c.trim(), met: false } : null;
+    if (c && typeof c === "object" && !Array.isArray(c)) {
+      const co = c;
+      const description = str2(co.description) ?? str2(co.criterion);
+      if (!description) return null;
+      return { description, met: co.met === true };
+    }
+    return null;
+  }).filter((c) => Boolean(c)) : [];
+  return {
+    strategy: str2(o2.strategy),
+    mechanism: str2(o2.mechanism),
+    startedAt: str2(o2.started_at),
+    observationWindowDays: window,
+    exitCriteria
+  };
+}
+function parseEnvironments(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const env of ENVIRONMENTS) {
+    const s = str2(v[env]);
+    if (s) out[env] = s;
+  }
+  return out;
+}
+function parseTarget(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o2 = raw;
+  const id = str2(o2.id);
+  if (!id) return null;
+  return {
+    id,
+    type: str2(o2.type) ?? "other",
+    locator: str2(o2.locator),
+    title: str2(o2.title),
+    lifecycle: str2(o2.lifecycle) ?? "candidate",
+    environments: parseEnvironments(o2.environments),
+    assessment: parseAssessment(o2.assessment),
+    usageEvidence: parseUsageEvidence(o2.usage_evidence),
+    dependsOnRemoval: strArray2(o2.depends_on_removal),
+    resource: str2(o2.resource),
+    module: str2(o2.module),
+    softDeprecation: parseSoftDeprecation(o2.soft_deprecation)
+  };
+}
+function parseTargets(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    const t = parseTarget(raw);
+    if (t) out.push(t);
+  }
+  return out;
+}
+function lifecycleCountsOf(targets) {
+  const counts = {};
+  for (const t of targets) counts[t.lifecycle] = (counts[t.lifecycle] ?? 0) + 1;
+  return counts;
+}
+function purposeFromBody2(body) {
+  const m2 = body.match(/^#{1,2}\s+Purpose\s*\n+([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m);
+  const text3 = m2 ? m2[1].trim() : "";
+  return text3 || null;
+}
+function getDeprecationPlans(dir) {
+  return discoverKnowledge(dir).filter((a2) => a2.type === DEPRECATION_ARTIFACT_TYPE).map((a2) => {
+    const fm = a2.rawFrontmatter;
+    const targets = parseTargets(fm.targets);
+    return {
+      id: a2.id || str2(fm.id) || a2.title,
+      title: a2.title || str2(fm.title) || a2.id,
+      path: a2.relPath,
+      status: str2(fm.status),
+      targetCount: targets.length,
+      lifecycleCounts: lifecycleCountsOf(targets)
+    };
+  }).sort((x2, y) => x2.id.localeCompare(y.id));
+}
+function getDeprecationPlan(dir, id) {
+  const match = discoverKnowledge(dir).find(
+    (a2) => a2.type === DEPRECATION_ARTIFACT_TYPE && (a2.id === id || a2.title === id)
+  );
+  if (!match) return null;
+  const raw = readFile(match.filePath);
+  const parsed = matter7(raw);
+  const fm = parsed.data ?? {};
+  const body = parsed.content.trim();
+  const targets = parseTargets(fm.targets);
+  return {
+    id: str2(fm.id) ?? match.id,
+    title: str2(fm.title) ?? match.title,
+    path: match.relPath,
+    status: str2(fm.status),
+    targetCount: targets.length,
+    lifecycleCounts: lifecycleCountsOf(targets),
+    purpose: str2(fm.purpose) ?? purposeFromBody2(body),
+    targets,
+    markdownBody: body
+  };
+}
+function validateTarget(target) {
+  const findings = [];
+  const at = target.id;
+  if (!isValidTargetType(String(target.type))) {
+    findings.push({ severity: "error", target: at, message: `Unknown target type: ${target.type}` });
+  }
+  if (!isValidLifecycleState(String(target.lifecycle))) {
+    findings.push({ severity: "error", target: at, message: `Unknown lifecycle state: ${target.lifecycle}` });
+  }
+  if (!target.locator) {
+    findings.push({ severity: "warning", target: at, message: "Target has no locator \u2014 it may be ambiguous." });
+  }
+  for (const [env, state] of Object.entries(target.environments)) {
+    if (!isValidEnvironmentState(String(state))) {
+      findings.push({ severity: "error", target: at, message: `Unknown environment state for ${env}: ${state}` });
+    }
+  }
+  const prodActive = target.environments.production === "active";
+  if (target.lifecycle === "completed") {
+    const stillActive = ENVIRONMENTS.filter((e) => target.environments[e] === "active");
+    if (stillActive.length > 0) {
+      findings.push({
+        severity: "error",
+        target: at,
+        message: `Target is 'completed' but still active in: ${stillActive.join(", ")}.`
+      });
+    }
+  }
+  if ((target.lifecycle === "production-changed" || target.lifecycle === "observing") && prodActive) {
+    findings.push({
+      severity: "error",
+      target: at,
+      message: `Target is '${target.lifecycle}' but production is still 'active'.`
+    });
+  }
+  return findings;
+}
+
 // ../cli/src/core/graph.ts
 var KNOWLEDGE3 = "knowledge";
 var RESOURCE_ROLE_EDGE = {
@@ -2779,9 +3025,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path9 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
-    if (path9) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path9 });
+    const path10 = layer2.files.map((f3) => `${KNOWLEDGE3}/${f3}`).find((rel) => exists(join(dir, rel)));
+    if (path10) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path10 });
       presentLayers.push(layer2.id);
     }
   }
@@ -2839,6 +3085,33 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addEdge(modId, resId, "depends_on");
     }
   }
+  for (const summary of getDeprecationPlans(dir)) {
+    const plan = getDeprecationPlan(dir, summary.id);
+    if (!plan) continue;
+    const planId = `deprecation-plan:${plan.id}`;
+    addNode({ id: planId, type: "deprecation-plan", label: `${plan.id} ${plan.title}`.trim(), path: plan.path, status: plan.status ?? void 0 });
+    for (const target of plan.targets) {
+      const targetId = `deprecation-target:${target.id}`;
+      addNode({ id: targetId, type: "deprecation-target", label: target.title ? `${target.id} ${target.title}` : target.id, path: plan.path, status: target.lifecycle });
+      addEdge(planId, targetId, "targets");
+      if (target.module) {
+        const moduleId = `module:${target.module}`;
+        addNode({ id: moduleId, type: "module", label: target.module });
+        addEdge(targetId, moduleId, "targets");
+      }
+      if (target.resource) {
+        const resourceId = `resource:${target.resource}`;
+        const title = resourceTitleById.get(target.resource);
+        addNode({ id: resourceId, type: "project-resource", label: title ? `${target.resource} ${title}` : target.resource });
+        addEdge(targetId, resourceId, "targets");
+      }
+      for (const dependency of target.dependsOnRemoval) {
+        const dependencyId = `deprecation-target:${dependency}`;
+        addNode({ id: dependencyId, type: "deprecation-target", label: dependency });
+        addEdge(targetId, dependencyId, "depends_on_removal");
+      }
+    }
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -2869,6 +3142,11 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addNode({ id: resId, type: "project-resource", label: title ? `${rel.id} ${title}`.trim() : rel.id });
       addEdge(wiNodeId, resId, RESOURCE_ROLE_EDGE[rel.role] ?? "uses");
     }
+    for (const ref of parseWorkItemDeprecationTargets(wi.rawFrontmatter)) {
+      const targetId = `deprecation-target:${ref.target}`;
+      addNode({ id: targetId, type: "deprecation-target", label: ref.target });
+      addEdge(wiNodeId, targetId, "targets");
+    }
     for (const dec of wi.decisions) {
       if (!dec || !dec.trim()) continue;
       const adrId = `adr:${dec}`;
@@ -3247,7 +3525,7 @@ function loadGraphHints(dir) {
 }
 
 // ../cli/src/services/installed-skills.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 var SKILLS_DIR = join("knowledge", "skills");
 function discoverInstalledSkills(dir) {
   const base = join(dir, SKILLS_DIR);
@@ -3257,7 +3535,7 @@ function discoverInstalledSkills(dir) {
     const skillFile = join(base, entry, "skill.md");
     if (!isFile(skillFile)) continue;
     try {
-      const { data } = matter7(readFile(skillFile));
+      const { data } = matter8(readFile(skillFile));
       if (data.type && String(data.type) !== "skill") continue;
       const id = String(data.id ?? entry);
       out.push({
@@ -4337,13 +4615,13 @@ function meaningful(text3) {
   });
 }
 function readPocSummary(dir) {
-  const path9 = join(dir, POC_ARTIFACT_PATH);
-  if (!exists(path9)) {
+  const path10 = join(dir, POC_ARTIFACT_PATH);
+  if (!exists(path10)) {
     return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
   }
   let markdown = "";
   try {
-    markdown = readFile(path9);
+    markdown = readFile(path10);
   } catch {
     return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
   }
@@ -4362,7 +4640,7 @@ function readPocSummary(dir) {
 
 // ../cli/src/core/poc-report.ts
 import { createHash } from "crypto";
-import matter8 from "gray-matter";
+import matter9 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$/;
@@ -4378,11 +4656,11 @@ function redactSecrets(value) {
     return line.replace(/([:=]\s*)\S+.*/, "$1[redacted]");
   }).join("\n");
 }
-function source(dir, path9, kind) {
-  const absolute = join(dir, path9);
+function source(dir, path10, kind) {
+  const absolute = join(dir, path10);
   if (!exists(absolute)) return null;
   const raw = readFile(absolute);
-  return { path: posix(path9), kind, digest: sha(raw), content: redactSecrets(raw) };
+  return { path: posix(path10), kind, digest: sha(raw), content: redactSecrets(raw) };
 }
 function reportFiles(dir) {
   const delivery = join(dir, "knowledge", "delivery");
@@ -4390,7 +4668,7 @@ function reportFiles(dir) {
     const match = name.match(reportName);
     if (!match) return [];
     try {
-      const parsed = matter8(readFile(join(delivery, name)));
+      const parsed = matter9(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")) : {};
@@ -4422,9 +4700,9 @@ function buildPocReportContext(dir) {
     };
   }
   const sources = [];
-  const add = (path9, kind) => {
-    if (sources.some((item2) => item2.path === posix(path9))) return;
-    const item = source(dir, path9, kind);
+  const add = (path10, kind) => {
+    if (sources.some((item2) => item2.path === posix(path10))) return;
+    const item = source(dir, path10, kind);
     if (item) sources.push(item);
   };
   add(POC_ARTIFACT_PATH, "poc");
@@ -4452,7 +4730,7 @@ function buildPocReportContext(dir) {
   const sourceFingerprint = sha(sources.map((item) => `${item.path}\0${item.digest}`).join("\n"));
   const status = !latestReport ? "missing" : latestReport.sourceFingerprint === sourceFingerprint ? "current" : "stale";
   const currentManifest = Object.fromEntries(sources.map((item) => [item.path, item.digest]));
-  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path9) => currentManifest[path9] !== latestReport?.sourceManifest[path9]).sort() : [];
+  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path10) => currentManifest[path10] !== latestReport?.sourceManifest[path10]).sort() : [];
   const sourceList = sources.map((item) => `- ${item.path} (${item.kind})`).join("\n") || "- No sources selected.";
   return {
     eligible: true,
@@ -4468,6 +4746,9 @@ function buildPocReportContext(dir) {
       `Canonical conclusion: ${poc.conclusion}. Do not contradict it.`,
       "Use the 15 canonical sections. Mark missing evidence as Not evaluated, Not applicable, or No evidence available.",
       "Distinguish measured, calculated, estimated, and projected values. Never include secret values.",
+      "Choose the representation that best communicates each grounded fact: Markdown tables for structured comparisons, Mermaid for grounded architecture, flows, or relationships, and prose for explanation and interpretation.",
+      "Do not invent data, entities, relationships, priorities, or metrics to create a table or diagram. Do not use ASCII diagrams when Mermaid can represent the same grounded flow.",
+      "In Traceability, use repository-relative Markdown links or paths. Never use file:/// URLs or local absolute filesystem paths.",
       "",
       "Selected sources:",
       sourceList
@@ -4600,10 +4881,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path9 = agentInstallPath(file);
-    const installed = isFile(join(dir, path9));
+    const path10 = agentInstallPath(file);
+    const installed = isFile(join(dir, path10));
     const group = agentGroupOf(file);
-    return { agentPath: path9, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path10, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -5033,7 +5314,7 @@ function deriveDeliveryCompletedStatus(dir) {
 }
 
 // ../cli/src/core/assets.ts
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 
 // ../cli/src/core/version.ts
 import { fileURLToPath } from "url";
@@ -5734,6 +6015,49 @@ After a POC has a canonical conclusion and Core has prepared its deterministic r
 - Use \`Not evaluated in this POC.\`, \`Not applicable.\`, or \`No evidence available.\` when sources do not support a section.
 - Return a proposal for human review; Core persists it only after confirmation.
 
+## Representation selection
+
+- Use prose for context, interpretation, rationale, findings, and conclusions.
+- Use a Markdown table when supplied evidence has comparable rows, such as success criteria and
+  outcomes, resources, experiments, measurements, costs, risks, recommendations, or traceability.
+- Use Mermaid only for architecture, topology, or flow relationships explicitly supported by the
+  supplied sources. Prefer it to an ASCII diagram when both can represent the same grounded flow.
+- Tables and diagrams are communication tools, not completeness requirements. Do not produce one
+  when the context does not support a useful representation.
+- Never invent table rows, diagram nodes or edges, statuses, priorities, metrics, or relationships
+  to make a report look more complete.
+- Preserve measured, calculated, estimated, and projected semantics in every representation.
+- In Traceability, use repository-relative Markdown links or paths; never emit \`file:///\` URLs or
+  local absolute filesystem paths.
+
+## Section representation guide
+
+| Section | Preferred representation when supported by evidence |
+|---|---|
+| Executive Summary | Snapshot table and short prose |
+| Problem and Objective | Prose |
+| Hypothesis and Success Criteria | Evaluation matrix |
+| Scope, Constraints and Non-goals | Compact bullets or table |
+| Technical Approach and Architecture | Mermaid and prose |
+| Infrastructure and Project Resources | Table, with optional Mermaid |
+| Implementation and Relevant Technical Decisions | Table or concise prose |
+| Experiments and Validation | Validation matrix |
+| Results and Measurements | Measurement tables |
+| Cost and Efficiency Analysis | Comparison table |
+| Observability and Operational Findings | Table or prose |
+| Findings, Learnings, Limitations and Risks | Structured matrix |
+| Conclusion | Status and concise prose |
+| Recommendation and Next Steps | Recommendation matrix only when priority is evidenced |
+| Traceability and Sources | Relative-link table or list |
+
+## Quality checklist
+
+- Structured evidence uses tables when clearer than prose.
+- Grounded architecture or flows use Mermaid when useful; no decorative or unsupported diagrams exist.
+- Tables and Mermaid preserve source grounding and measurement semantics.
+- Traceability contains repository-portable paths.
+- The report is scannable before reading the full narrative.
+
 ## Required structure
 
 1. Executive Summary
@@ -8301,7 +8625,7 @@ function canonicalSkills() {
 }
 function versionOf(content) {
   try {
-    const v = matter9(content).data.version;
+    const v = matter10(content).data.version;
     return v === void 0 || v === null ? null : String(v);
   } catch {
     return null;
@@ -9141,7 +9465,7 @@ function renderRouteCompact(route) {
 }
 
 // ../cli/src/core/metadata-health.ts
-import matter10 from "gray-matter";
+import matter11 from "gray-matter";
 var KNOWLEDGE_FILES2 = [
   "knowledge/business/business.md",
   "knowledge/product/product.md",
@@ -9161,7 +9485,7 @@ function analyzeMetadataHealth(dir) {
     let data;
     try {
       const raw = readFile(p);
-      data = matter10(raw).data;
+      data = matter11(raw).data;
     } catch {
       continue;
     }
@@ -9193,7 +9517,7 @@ function analyzeMetadataHealth(dir) {
         if (isFile(p) && entry.endsWith(".md")) {
           try {
             const raw = readFile(p);
-            const fm = matter10(raw).data;
+            const fm = matter11(raw).data;
             if (fm.status === "done") {
               const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
               findings.push({
@@ -10061,7 +10385,7 @@ function buildGuardHistory(dir) {
     const d3 = hotspotDir(t.code_path);
     hotspotMap.set(d3, (hotspotMap.get(d3) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path9, warnings]) => ({ path: path9, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path10, warnings]) => ({ path: path10, warnings })).sort((a2, b2) => b2.warnings - a2.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -10148,7 +10472,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter11(readFile(wi.filePath)).content;
+      const body = matter12(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++;
@@ -10861,7 +11185,7 @@ function serializeDriftJson(r2) {
 }
 
 // src/workitems.ts
-import matter12 from "gray-matter";
+import matter13 from "gray-matter";
 var VALID_SOURCES2 = /* @__PURE__ */ new Set(["manual", "roadmap", "jira", "github", "notion", "xlsx", "csv", "api", "external", "unknown"]);
 function optStr3(v) {
   return typeof v === "string" && v.trim() ? v.trim() : void 0;
@@ -10884,7 +11208,7 @@ function parseSource(data) {
   return { type: "unknown", inferred: true };
 }
 var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
-function strArray2(v) {
+function strArray3(v) {
   return Array.isArray(v) ? v.map((x2) => String(x2)).filter(Boolean) : [];
 }
 function lifecycleOf(data, relPath) {
@@ -10952,15 +11276,15 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter12(raw);
+      parsed = matter13(raw);
     } catch {
       continue;
     }
     const data = parsed.data;
     if (!data.type) continue;
     const status = lifecycleOf(data, rel);
-    const code = strArray2(data.code);
-    const domains = strArray2(data.domains);
+    const code = strArray3(data.code);
+    const domains = strArray3(data.domains);
     const source3 = parseSource(data);
     const readiness = status === "draft" ? assessReadiness(data, parsed.content, code, domains, source3) : void 0;
     items.push({
@@ -10972,9 +11296,9 @@ function listWorkItems(root) {
       path: rel,
       summary: String(data.summary ?? "") || firstParagraph2(parsed.content),
       code,
-      capabilities: strArray2(data.capabilities),
-      decisions: strArray2(data.decisions),
-      capsules: strArray2(data.capsules),
+      capabilities: strArray3(data.capabilities),
+      decisions: strArray3(data.decisions),
+      capsules: strArray3(data.capsules),
       source: source3,
       domains,
       readiness,
@@ -11451,14 +11775,14 @@ function getPrompt(root, name) {
 }
 
 // src/tools.ts
-import matter16 from "gray-matter";
+import matter20 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 matter13 from "gray-matter";
+import matter14 from "gray-matter";
 import matter22 from "gray-matter";
 import { parse as parseYaml62, stringify as stringifyYaml42 } from "yaml";
 import { parse as parseYaml22 } from "yaml";
@@ -11468,28 +11792,31 @@ import { parse as parseYaml42, stringify as stringifyYaml22 } from "yaml";
 import matter32 from "gray-matter";
 import matter42 from "gray-matter";
 import matter52 from "gray-matter";
+import matter62 from "gray-matter";
 import { parse as parseYaml72 } from "yaml";
 import { createHash as createHash2 } from "crypto";
-import matter62 from "gray-matter";
 import matter72 from "gray-matter";
+import matter82 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 matter82 from "gray-matter";
 import matter92 from "gray-matter";
 import matter102 from "gray-matter";
+import matter112 from "gray-matter";
 import { parse as parseYaml82, stringify as stringifyYaml52 } from "yaml";
 import fs4 from "fs";
 import path4 from "path";
 import crypto2 from "crypto";
-import matter112 from "gray-matter";
+import matter122 from "gray-matter";
 import crypto3 from "crypto";
 import fs5 from "fs";
-import matter122 from "gray-matter";
 import matter132 from "gray-matter";
+import matter142 from "gray-matter";
 import { parse as parseYaml92, stringify as stringifyYaml6 } from "yaml";
 import { parse as parseYaml102, stringify as stringifyYaml7 } from "yaml";
-import matter14 from "gray-matter";
+import matter15 from "gray-matter";
+import matter16 from "gray-matter";
+import matter17 from "gray-matter";
 function exists2(p) {
   return fs3.existsSync(p);
 }
@@ -11608,8 +11935,8 @@ function loadConfig2(dir) {
   const parsed = configSchema2.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path52 = i.path.join(".");
-      return path52 ? `  - ${path52}: ${i.message}` : `  - ${i.message}`;
+      const path62 = i.path.join(".");
+      return path62 ? `  - ${path62}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError2(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -11665,7 +11992,7 @@ function parseImpactAnalysis2(data) {
 }
 function parseArtifact2(filePath, raw) {
   try {
-    const { data } = matter13(raw);
+    const { data } = matter14(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -11718,7 +12045,7 @@ function readArtifacts2(archDir) {
   walkDir(archDir);
   return artifacts;
 }
-var LIFECYCLE_STATES2 = [
+var LIFECYCLE_STATES3 = [
   "draft",
   "ready",
   "in-progress",
@@ -11733,7 +12060,7 @@ var LEGACY_STATUS_MAP2 = {
   canceled: "archived",
   "in-progress": "in-progress"
 };
-var STATE_SET2 = new Set(LIFECYCLE_STATES2);
+var STATE_SET2 = new Set(LIFECYCLE_STATES3);
 function isLifecycleState2(s) {
   return STATE_SET2.has(s);
 }
@@ -11755,7 +12082,7 @@ function lifecycleStateOf2(item) {
   return "ready";
 }
 function emptyLifecycleCounts2() {
-  return Object.fromEntries(LIFECYCLE_STATES2.map((s) => [s, 0]));
+  return Object.fromEntries(LIFECYCLE_STATES3.map((s) => [s, 0]));
 }
 var ARCH_DIR3 = "knowledge";
 function toPosix7(p) {
@@ -11813,11 +12140,11 @@ function moduleArtifactCoverage2(dir, id) {
   };
 }
 function loadMappedModules2(dir) {
-  const path52 = join3(dir, DESCRIPTOR_PATH2);
-  if (!exists2(path52)) return [];
+  const path62 = join3(dir, DESCRIPTOR_PATH2);
+  if (!exists2(path62)) return [];
   let parsed;
   try {
-    parsed = parseYaml32(readFile2(path52));
+    parsed = parseYaml32(readFile2(path62));
   } catch {
     return [];
   }
@@ -13220,10 +13547,10 @@ function suggestInitiativesForExternalItem(dir, integration, externalId) {
   );
 }
 var RESOURCE_ARTIFACT_TYPE2 = "project-resource";
-function str2(v) {
+function str3(v) {
   return typeof v === "string" && v.trim() ? v.trim() : null;
 }
-function strArray3(v) {
+function strArray4(v) {
   if (Array.isArray(v)) return v.map((x2) => String(x2).trim()).filter(Boolean);
   if (typeof v === "string" && v.trim()) return [v.trim()];
   return [];
@@ -13234,16 +13561,16 @@ function parseInterfaces2(v) {
   for (const raw of v) {
     if (!raw || typeof raw !== "object") continue;
     const o2 = raw;
-    const type = str2(o2.type);
+    const type = str3(o2.type);
     if (!type) continue;
     out.push({
       type,
-      tool: str2(o2.tool),
-      provider: str2(o2.provider),
-      purpose: str2(o2.purpose),
-      operations: strArray3(o2.operations),
-      environments: strArray3(o2.environments),
-      constraints: str2(o2.constraints)
+      tool: str3(o2.tool),
+      provider: str3(o2.provider),
+      purpose: str3(o2.purpose),
+      operations: strArray4(o2.operations),
+      environments: strArray4(o2.environments),
+      constraints: str3(o2.constraints)
     });
   }
   return out;
@@ -13252,7 +13579,7 @@ function parseBoundaries2(v) {
   if (!v || typeof v !== "object" || Array.isArray(v)) return {};
   const out = {};
   for (const [env, val] of Object.entries(v)) {
-    const list22 = strArray3(val);
+    const list22 = strArray4(val);
     if (list22.length > 0) out[env] = list22;
   }
   return out;
@@ -13260,17 +13587,17 @@ function parseBoundaries2(v) {
 function parseAuth2(v) {
   if (!v || typeof v !== "object" || Array.isArray(v)) return { mode: null, refs: [] };
   const o2 = v;
-  const refs = strArray3(o2.refs).filter((r2) => !r2.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r2));
-  return { mode: str2(o2.mode), refs };
+  const refs = strArray4(o2.refs).filter((r2) => !r2.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r2));
+  return { mode: str3(o2.mode), refs };
 }
 function parseScope2(v) {
   if (!v || typeof v !== "object" || Array.isArray(v)) return null;
   const o2 = v;
-  const type = str2(o2.type);
+  const type = str3(o2.type);
   if (!type) return null;
-  return { type, module: str2(o2.module) };
+  return { type, module: str3(o2.module) };
 }
-function purposeFromBody2(body) {
+function purposeFromBody3(body) {
   const m2 = body.match(/^#{1,2}\s+Purpose\s*\n+([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m);
   const text22 = m2 ? m2[1].trim() : "";
   return text22 || null;
@@ -13279,17 +13606,17 @@ function toDetail2(filePath, relPath, raw) {
   const parsed = matter42(raw);
   const fm = parsed.data ?? {};
   const body = parsed.content.trim();
-  const id = str2(fm.id) ?? "";
+  const id = str3(fm.id) ?? "";
   return {
     id,
-    title: str2(fm.title) ?? id,
-    resourceType: str2(fm.resource_type),
-    provider: str2(fm.provider),
-    environments: strArray3(fm.environments),
+    title: str3(fm.title) ?? id,
+    resourceType: str3(fm.resource_type),
+    provider: str3(fm.provider),
+    environments: strArray4(fm.environments),
     scope: parseScope2(fm.scope),
-    modules: strArray3(fm.modules),
+    modules: strArray4(fm.modules),
     path: relPath,
-    purpose: str2(fm.purpose) ?? purposeFromBody2(body),
+    purpose: str3(fm.purpose) ?? purposeFromBody3(body),
     interfaces: parseInterfaces2(fm.access_interfaces),
     boundaries: parseBoundaries2(fm.access_boundaries),
     ...(() => {
@@ -13303,13 +13630,13 @@ function getResources2(dir) {
   return discoverKnowledge2(dir).filter((a2) => a2.type === RESOURCE_ARTIFACT_TYPE2).map((a2) => {
     const fm = a2.rawFrontmatter;
     return {
-      id: a2.id || str2(fm.id) || a2.title,
-      title: a2.title || str2(fm.title) || a2.id,
-      resourceType: str2(fm.resource_type),
-      provider: str2(fm.provider),
-      environments: strArray3(fm.environments),
+      id: a2.id || str3(fm.id) || a2.title,
+      title: a2.title || str3(fm.title) || a2.id,
+      resourceType: str3(fm.resource_type),
+      provider: str3(fm.provider),
+      environments: strArray4(fm.environments),
       scope: parseScope2(fm.scope),
-      modules: strArray3(fm.modules),
+      modules: strArray4(fm.modules),
       path: a2.relPath
     };
   }).sort((x2, y) => x2.id.localeCompare(y.id));
@@ -13329,12 +13656,184 @@ function parseWorkItemResources2(fm) {
   for (const raw of v) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
     const o2 = raw;
-    const id = str2(o2.id);
+    const id = str3(o2.id);
     if (!id) continue;
-    out.push({ id, role: str2(o2.role) ?? "affected" });
+    out.push({ id, role: str3(o2.role) ?? "affected" });
   }
   return out;
 }
+var DEPRECATION_ARTIFACT_TYPE2 = "deprecation-plan";
+var ENVIRONMENTS2 = ["development", "test", "production"];
+var EVIDENCE_SIGNALS2 = [
+  "static",
+  "runtime",
+  "database",
+  "external_consumers",
+  "human_review"
+];
+function str22(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function parseWorkItemDeprecationTargets2(fm) {
+  const v = fm.deprecation_targets;
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (typeof raw === "string") {
+      const s = raw.trim();
+      if (!s) continue;
+      const slash = s.indexOf("/");
+      if (slash > 0) out.push({ plan: s.slice(0, slash).trim(), target: s.slice(slash + 1).trim() });
+      else out.push({ plan: null, target: s });
+      continue;
+    }
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      const o2 = raw;
+      const target = str22(o2.target) ?? str22(o2.id);
+      if (!target) continue;
+      out.push({ plan: str22(o2.plan), target });
+    }
+  }
+  return out;
+}
+function strArray22(v) {
+  if (Array.isArray(v)) return v.map((x2) => String(x2).trim()).filter(Boolean);
+  if (typeof v === "string" && v.trim()) return [v.trim()];
+  return [];
+}
+function parseAssessment2(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    return { unusedConfidence: null, blastRadius: null, reversibility: null };
+  }
+  const o2 = v;
+  return {
+    unusedConfidence: str22(o2.unused_confidence),
+    blastRadius: str22(o2.blast_radius),
+    reversibility: str22(o2.reversibility)
+  };
+}
+function parseUsageEvidence2(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const signal of EVIDENCE_SIGNALS2) {
+    const raw = v[signal];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o2 = raw;
+    out[signal] = {
+      status: str22(o2.status) ?? "unknown",
+      quality: str22(o2.quality) ?? "unknown",
+      detail: str22(o2.detail)
+    };
+  }
+  return out;
+}
+function parseSoftDeprecation2(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  const o2 = v;
+  const windowRaw = o2.observation_window_days;
+  const window = typeof windowRaw === "number" && Number.isFinite(windowRaw) && windowRaw >= 0 ? Math.floor(windowRaw) : null;
+  const exitCriteria = Array.isArray(o2.exit_criteria) ? o2.exit_criteria.map((c) => {
+    if (typeof c === "string") return c.trim() ? { description: c.trim(), met: false } : null;
+    if (c && typeof c === "object" && !Array.isArray(c)) {
+      const co = c;
+      const description = str22(co.description) ?? str22(co.criterion);
+      if (!description) return null;
+      return { description, met: co.met === true };
+    }
+    return null;
+  }).filter((c) => Boolean(c)) : [];
+  return {
+    strategy: str22(o2.strategy),
+    mechanism: str22(o2.mechanism),
+    startedAt: str22(o2.started_at),
+    observationWindowDays: window,
+    exitCriteria
+  };
+}
+function parseEnvironments2(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const env of ENVIRONMENTS2) {
+    const s = str22(v[env]);
+    if (s) out[env] = s;
+  }
+  return out;
+}
+function parseTarget2(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o2 = raw;
+  const id = str22(o2.id);
+  if (!id) return null;
+  return {
+    id,
+    type: str22(o2.type) ?? "other",
+    locator: str22(o2.locator),
+    title: str22(o2.title),
+    lifecycle: str22(o2.lifecycle) ?? "candidate",
+    environments: parseEnvironments2(o2.environments),
+    assessment: parseAssessment2(o2.assessment),
+    usageEvidence: parseUsageEvidence2(o2.usage_evidence),
+    dependsOnRemoval: strArray22(o2.depends_on_removal),
+    resource: str22(o2.resource),
+    module: str22(o2.module),
+    softDeprecation: parseSoftDeprecation2(o2.soft_deprecation)
+  };
+}
+function parseTargets2(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    const t = parseTarget2(raw);
+    if (t) out.push(t);
+  }
+  return out;
+}
+function lifecycleCountsOf2(targets) {
+  const counts = {};
+  for (const t of targets) counts[t.lifecycle] = (counts[t.lifecycle] ?? 0) + 1;
+  return counts;
+}
+function purposeFromBody22(body) {
+  const m2 = body.match(/^#{1,2}\s+Purpose\s*\n+([\s\S]*?)(?=\n#{1,2}\s|\s*$)/m);
+  const text22 = m2 ? m2[1].trim() : "";
+  return text22 || null;
+}
+function getDeprecationPlans2(dir) {
+  return discoverKnowledge2(dir).filter((a2) => a2.type === DEPRECATION_ARTIFACT_TYPE2).map((a2) => {
+    const fm = a2.rawFrontmatter;
+    const targets = parseTargets2(fm.targets);
+    return {
+      id: a2.id || str22(fm.id) || a2.title,
+      title: a2.title || str22(fm.title) || a2.id,
+      path: a2.relPath,
+      status: str22(fm.status),
+      targetCount: targets.length,
+      lifecycleCounts: lifecycleCountsOf2(targets)
+    };
+  }).sort((x2, y) => x2.id.localeCompare(y.id));
+}
+function getDeprecationPlan2(dir, id) {
+  const match = discoverKnowledge2(dir).find(
+    (a2) => a2.type === DEPRECATION_ARTIFACT_TYPE2 && (a2.id === id || a2.title === id)
+  );
+  if (!match) return null;
+  const raw = readFile2(match.filePath);
+  const parsed = matter52(raw);
+  const fm = parsed.data ?? {};
+  const body = parsed.content.trim();
+  const targets = parseTargets2(fm.targets);
+  return {
+    id: str22(fm.id) ?? match.id,
+    title: str22(fm.title) ?? match.title,
+    path: match.relPath,
+    status: str22(fm.status),
+    targetCount: targets.length,
+    lifecycleCounts: lifecycleCountsOf2(targets),
+    purpose: str22(fm.purpose) ?? purposeFromBody22(body),
+    targets,
+    markdownBody: body
+  };
+}
 var KNOWLEDGE22 = "knowledge";
 var RESOURCE_ROLE_EDGE2 = {
   affected: "affects",
@@ -13378,9 +13877,9 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path52 = layer2.files.map((f3) => `${KNOWLEDGE22}/${f3}`).find((rel) => exists2(join3(dir, rel)));
-    if (path52) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path52 });
+    const path62 = layer2.files.map((f3) => `${KNOWLEDGE22}/${f3}`).find((rel) => exists2(join3(dir, rel)));
+    if (path62) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path62 });
       presentLayers.push(layer2.id);
     }
   }
@@ -13438,6 +13937,33 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addEdge(modId, resId, "depends_on");
     }
   }
+  for (const summary of getDeprecationPlans2(dir)) {
+    const plan = getDeprecationPlan2(dir, summary.id);
+    if (!plan) continue;
+    const planId = `deprecation-plan:${plan.id}`;
+    addNode({ id: planId, type: "deprecation-plan", label: `${plan.id} ${plan.title}`.trim(), path: plan.path, status: plan.status ?? void 0 });
+    for (const target of plan.targets) {
+      const targetId = `deprecation-target:${target.id}`;
+      addNode({ id: targetId, type: "deprecation-target", label: target.title ? `${target.id} ${target.title}` : target.id, path: plan.path, status: target.lifecycle });
+      addEdge(planId, targetId, "targets");
+      if (target.module) {
+        const moduleId = `module:${target.module}`;
+        addNode({ id: moduleId, type: "module", label: target.module });
+        addEdge(targetId, moduleId, "targets");
+      }
+      if (target.resource) {
+        const resourceId = `resource:${target.resource}`;
+        const title = resourceTitleById.get(target.resource);
+        addNode({ id: resourceId, type: "project-resource", label: title ? `${target.resource} ${title}` : target.resource });
+        addEdge(targetId, resourceId, "targets");
+      }
+      for (const dependency of target.dependsOnRemoval) {
+        const dependencyId = `deprecation-target:${dependency}`;
+        addNode({ id: dependencyId, type: "deprecation-target", label: dependency });
+        addEdge(targetId, dependencyId, "depends_on_removal");
+      }
+    }
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -13468,6 +13994,11 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addNode({ id: resId, type: "project-resource", label: title ? `${rel.id} ${title}`.trim() : rel.id });
       addEdge(wiNodeId, resId, RESOURCE_ROLE_EDGE2[rel.role] ?? "uses");
     }
+    for (const ref of parseWorkItemDeprecationTargets2(wi.rawFrontmatter)) {
+      const targetId = `deprecation-target:${ref.target}`;
+      addNode({ id: targetId, type: "deprecation-target", label: ref.target });
+      addEdge(wiNodeId, targetId, "targets");
+    }
     for (const dec of wi.decisions) {
       if (!dec || !dec.trim()) continue;
       const adrId = `adr:${dec}`;
@@ -13827,13 +14358,13 @@ function meaningful2(text22) {
   });
 }
 function readPocSummary2(dir) {
-  const path52 = join3(dir, POC_ARTIFACT_PATH2);
-  if (!exists2(path52)) {
+  const path62 = join3(dir, POC_ARTIFACT_PATH2);
+  if (!exists2(path62)) {
     return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
   }
   let markdown = "";
   try {
-    markdown = readFile2(path52);
+    markdown = readFile2(path62);
   } catch {
     return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
   }
@@ -13864,11 +14395,11 @@ function redactSecrets2(value) {
     return line.replace(/([:=]\s*)\S+.*/, "$1[redacted]");
   }).join("\n");
 }
-function source2(dir, path52, kind) {
-  const absolute = join3(dir, path52);
+function source2(dir, path62, kind) {
+  const absolute = join3(dir, path62);
   if (!exists2(absolute)) return null;
   const raw = readFile2(absolute);
-  return { path: posix2(path52), kind, digest: sha2(raw), content: redactSecrets2(raw) };
+  return { path: posix2(path62), kind, digest: sha2(raw), content: redactSecrets2(raw) };
 }
 function reportFiles2(dir) {
   const delivery = join3(dir, "knowledge", "delivery");
@@ -13876,7 +14407,7 @@ function reportFiles2(dir) {
     const match = name.match(reportName2);
     if (!match) return [];
     try {
-      const parsed = matter62(readFile2(join3(delivery, name)));
+      const parsed = matter72(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")) : {};
@@ -13908,9 +14439,9 @@ function buildPocReportContext2(dir) {
     };
   }
   const sources = [];
-  const add = (path52, kind) => {
-    if (sources.some((item2) => item2.path === posix2(path52))) return;
-    const item = source2(dir, path52, kind);
+  const add = (path62, kind) => {
+    if (sources.some((item2) => item2.path === posix2(path62))) return;
+    const item = source2(dir, path62, kind);
     if (item) sources.push(item);
   };
   add(POC_ARTIFACT_PATH2, "poc");
@@ -13938,7 +14469,7 @@ function buildPocReportContext2(dir) {
   const sourceFingerprint = sha2(sources.map((item) => `${item.path}\0${item.digest}`).join("\n"));
   const status = !latestReport ? "missing" : latestReport.sourceFingerprint === sourceFingerprint ? "current" : "stale";
   const currentManifest = Object.fromEntries(sources.map((item) => [item.path, item.digest]));
-  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path52) => currentManifest[path52] !== latestReport?.sourceManifest[path52]).sort() : [];
+  const changesSinceLatest = status === "stale" ? [.../* @__PURE__ */ new Set([...Object.keys(currentManifest), ...Object.keys(latestReport?.sourceManifest ?? {})])].filter((path62) => currentManifest[path62] !== latestReport?.sourceManifest[path62]).sort() : [];
   const sourceList = sources.map((item) => `- ${item.path} (${item.kind})`).join("\n") || "- No sources selected.";
   return {
     eligible: true,
@@ -13954,6 +14485,9 @@ function buildPocReportContext2(dir) {
       `Canonical conclusion: ${poc.conclusion}. Do not contradict it.`,
       "Use the 15 canonical sections. Mark missing evidence as Not evaluated, Not applicable, or No evidence available.",
       "Distinguish measured, calculated, estimated, and projected values. Never include secret values.",
+      "Choose the representation that best communicates each grounded fact: Markdown tables for structured comparisons, Mermaid for grounded architecture, flows, or relationships, and prose for explanation and interpretation.",
+      "Do not invent data, entities, relationships, priorities, or metrics to create a table or diagram. Do not use ASCII diagrams when Mermaid can represent the same grounded flow.",
+      "In Traceability, use repository-relative Markdown links or paths. Never use file:/// URLs or local absolute filesystem paths.",
       "",
       "Selected sources:",
       sourceList
@@ -13972,7 +14506,7 @@ function canonicalReport(context, proposal) {
     source_manifest: Object.fromEntries(context.sources.map((item) => [item.path, item.digest]))
   };
   if (supersedes) data.supersedes = supersedes;
-  return matter62.stringify(redactSecrets2(proposal).trimEnd() + "\n", data);
+  return matter72.stringify(redactSecrets2(proposal).trimEnd() + "\n", data);
 }
 function persistPocReport(dir, proposal, opts = {}) {
   const context = buildPocReportContext2(dir);
@@ -14678,6 +15212,49 @@ After a POC has a canonical conclusion and Core has prepared its deterministic r
 - Use \`Not evaluated in this POC.\`, \`Not applicable.\`, or \`No evidence available.\` when sources do not support a section.
 - Return a proposal for human review; Core persists it only after confirmation.
 
+## Representation selection
+
+- Use prose for context, interpretation, rationale, findings, and conclusions.
+- Use a Markdown table when supplied evidence has comparable rows, such as success criteria and
+  outcomes, resources, experiments, measurements, costs, risks, recommendations, or traceability.
+- Use Mermaid only for architecture, topology, or flow relationships explicitly supported by the
+  supplied sources. Prefer it to an ASCII diagram when both can represent the same grounded flow.
+- Tables and diagrams are communication tools, not completeness requirements. Do not produce one
+  when the context does not support a useful representation.
+- Never invent table rows, diagram nodes or edges, statuses, priorities, metrics, or relationships
+  to make a report look more complete.
+- Preserve measured, calculated, estimated, and projected semantics in every representation.
+- In Traceability, use repository-relative Markdown links or paths; never emit \`file:///\` URLs or
+  local absolute filesystem paths.
+
+## Section representation guide
+
+| Section | Preferred representation when supported by evidence |
+|---|---|
+| Executive Summary | Snapshot table and short prose |
+| Problem and Objective | Prose |
+| Hypothesis and Success Criteria | Evaluation matrix |
+| Scope, Constraints and Non-goals | Compact bullets or table |
+| Technical Approach and Architecture | Mermaid and prose |
+| Infrastructure and Project Resources | Table, with optional Mermaid |
+| Implementation and Relevant Technical Decisions | Table or concise prose |
+| Experiments and Validation | Validation matrix |
+| Results and Measurements | Measurement tables |
+| Cost and Efficiency Analysis | Comparison table |
+| Observability and Operational Findings | Table or prose |
+| Findings, Learnings, Limitations and Risks | Structured matrix |
+| Conclusion | Status and concise prose |
+| Recommendation and Next Steps | Recommendation matrix only when priority is evidenced |
+| Traceability and Sources | Relative-link table or list |
+
+## Quality checklist
+
+- Structured evidence uses tables when clearer than prose.
+- Grounded architecture or flows use Mermaid when useful; no decorative or unsupported diagrams exist.
+- Tables and Mermaid preserve source grounding and measurement semantics.
+- Traceability contains repository-portable paths.
+- The report is scannable before reading the full narrative.
+
 ## Required structure
 
 1. Executive Summary
@@ -17895,6 +18472,8 @@ function getWorkItem(dir, workItemId) {
     markdownBody: body.trim(),
     // External systems this WI relates to (WI-030), separate from affectedModules (code).
     resources: parseWorkItemResources2(fm),
+    // Deprecation Targets this WI retires (WI-050), referenced not copied.
+    deprecationTargets: parseWorkItemDeprecationTargets2(fm),
     ...parseSystemImpact(dir, fm)
   };
   return { ...detail, refinement: computeRefinementStatus(detail) };
@@ -17903,8 +18482,8 @@ function parseGraphReason(v) {
   if (!v || typeof v !== "object") return null;
   const o2 = v;
   const relationship = typeof o2.relationship === "string" && o2.relationship.trim() ? o2.relationship.trim() : null;
-  const path52 = Array.isArray(o2.path) ? o2.path.map(String).filter(Boolean) : [];
-  return relationship || path52.length ? { relationship, path: path52 } : null;
+  const path62 = Array.isArray(o2.path) ? o2.path.map(String).filter(Boolean) : [];
+  return relationship || path62.length ? { relationship, path: path62 } : null;
 }
 function parseExplain(o2) {
   const refs = Array.isArray(o2.evidence) ? o2.evidence : Array.isArray(o2.evidence_refs) ? o2.evidence_refs : [];
@@ -17959,7 +18538,7 @@ function parseOriginalSnapshot(fm) {
 function readBody(filePath) {
   try {
     const raw = readFile2(filePath);
-    return matter102(raw).content;
+    return matter112(raw).content;
   } catch {
     return "";
   }
@@ -18244,7 +18823,7 @@ function ensureH1(body, title) {
 ${trimmed}`;
 }
 function serialize2(data, body) {
-  return matter112.stringify(`
+  return matter122.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -18609,6 +19188,61 @@ function buildRefinementHandoff(dir, workItemId) {
     text: lines.join("\n")
   };
 }
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function isStrongNoUsage(sig) {
+  return sig.status === "no-usage" && (sig.quality === "observed-fact" || sig.quality === "human-confirmed");
+}
+function deriveUnusedConfidence(evidence) {
+  const present = EVIDENCE_SIGNALS2.map((name) => ({ name, sig: evidence[name] })).filter(
+    (e) => Boolean(e.sig)
+  );
+  const usageFound = present.filter((e) => e.sig.status === "usage-found");
+  if (usageFound.length > 0) {
+    return {
+      confidence: "in-use",
+      requiresHumanConfirmation: false,
+      rationale: [`Usage found via: ${usageFound.map((e) => e.name).join(", ")}.`]
+    };
+  }
+  const strong = present.filter((e) => isStrongNoUsage(e.sig));
+  const unknown = present.filter((e) => e.sig.status === "unknown");
+  const notEvaluated = EVIDENCE_SIGNALS2.filter(
+    (name) => !evidence[name] || evidence[name]?.status === "not-evaluated"
+  );
+  const rationale = [];
+  if (strong.length > 0) rationale.push(`No usage observed via: ${strong.map((e) => e.name).join(", ")}.`);
+  if (unknown.length > 0) {
+    rationale.push(`Unknown (looked but could not determine): ${unknown.map((e) => e.name).join(", ")} \u2014 NOT treated as no-usage.`);
+  }
+  if (notEvaluated.length > 0) {
+    rationale.push(`Not evaluated: ${notEvaluated.join(", ")} \u2014 absence of a reference is not evidence of no usage.`);
+  }
+  let confidence;
+  if (strong.length === 0) {
+    confidence = "insufficient-evidence";
+  } else if (unknown.length > 0) {
+    confidence = "medium";
+  } else if (strong.length >= 2) {
+    confidence = "high";
+  } else {
+    confidence = "medium";
+  }
+  return { confidence, requiresHumanConfirmation: true, rationale };
+}
+var CANDIDATE_DISCOVERY_GUIDANCE = [
+  "Propose deprecation candidates from multiple sources: static references (code/routes/UI/jobs),",
+  "the System Graph (dependencies and blast radius), Legacy Knowledge (risks/unknowns/modernization",
+  "candidates), Project Resources (databases/external systems and their boundaries), runtime evidence",
+  "when telemetry exists, and database metadata when reachable.",
+  "",
+  "Rules:",
+  "- Discovery is a PROPOSAL, not a materialization: never create or retire anything automatically.",
+  "- Always explain WHY something is a candidate, citing the signal(s) observed.",
+  "- Absence of a reference is NOT evidence of no usage. If a source cannot be evaluated, record it",
+  "  as not-evaluated/unknown and require human investigation \u2014 never collapse it to no-usage.",
+  "- A modernization candidate is not automatically a deprecation target.",
+  "- Soft deprecation precedes physical removal; order retirements by dependency, dependents first."
+].join("\n");
 var WorkItemNotReadyError = class extends Error {
   constructor(workItemId, actualState) {
     super(`Work Item "${workItemId}" must be in "ready" state to produce an Implementation Handoff, but is "${actualState}".`);
@@ -18639,6 +19273,16 @@ function buildImplementationHandoff(dir, workItemId) {
   const domains = match.domains;
   const scopeConfidence = match.scopeConfidence;
   const wiResources = parseWorkItemResources2(match.rawFrontmatter);
+  const wiDeprecationRefs = parseWorkItemDeprecationTargets2(match.rawFrontmatter);
+  const resolveTarget = (ref) => {
+    const plans = ref.plan ? [getDeprecationPlan2(dir, ref.plan)].filter(Boolean) : getDeprecationPlans2(dir).map((p) => getDeprecationPlan2(dir, p.id));
+    for (const p of plans) {
+      if (!p) continue;
+      const t = p.targets.find((x2) => x2.id.toUpperCase() === ref.target.toUpperCase());
+      if (t) return { planId: p.id, target: t };
+    }
+    return null;
+  };
   const lines = [
     `Implement Work Item ${wiId} \u2014 "${wiTitle}" \u2014 in project "${projectName}" using Kaddo.`,
     "",
@@ -18763,6 +19407,48 @@ function buildImplementationHandoff(dir, workItemId) {
       "installed or connected. Do not execute any interface or migration without explicit human confirmation."
     );
   }
+  if (wiDeprecationRefs.length > 0) {
+    lines.push(
+      "",
+      "--- Relevant Deprecation Targets ---",
+      "",
+      "This Work Item is part of a Controlled Deprecation plan. It RETIRES the targets below. Soft",
+      "deprecation precedes physical removal; in Dev/Test you may remove code/endpoints/dev-test data",
+      "when the resource boundary allows and there is confirmation. A production change needs a Runbook",
+      "and explicit human approval \u2014 never execute a destructive production operation autonomously."
+    );
+    for (const ref of wiDeprecationRefs) {
+      const resolved = resolveTarget(ref);
+      if (!resolved) {
+        lines.push("", `- ${ref.target}${ref.plan ? ` (plan ${ref.plan})` : ""} \u2014 target not found in any Deprecation Plan.`);
+        continue;
+      }
+      const { planId, target: t } = resolved;
+      lines.push("", `- ${t.id} [${t.type}] \u2014 plan ${planId}, lifecycle: ${t.lifecycle}`);
+      if (t.locator) lines.push(`    locator: ${t.locator}`);
+      const envs = Object.entries(t.environments).map(([e, s]) => `${e}=${s}`).join(" ");
+      if (envs) lines.push(`    environments: ${envs}`);
+      const unused = deriveUnusedConfidence(t.usageEvidence);
+      lines.push(`    unused confidence: ${unused.confidence}${unused.requiresHumanConfirmation ? " (human confirmation required)" : ""}`);
+      if (t.assessment.blastRadius) lines.push(`    blast radius: ${t.assessment.blastRadius}`);
+      if (t.assessment.reversibility) lines.push(`    reversibility: ${t.assessment.reversibility}`);
+      if (t.dependsOnRemoval.length > 0) lines.push(`    depends_on_removal: ${t.dependsOnRemoval.join(", ")} (retire these first)`);
+      if (t.resource) {
+        const res = getResource2(dir, t.resource);
+        if (res) {
+          const bounds = Object.entries(res.boundaries).map(([env, ops]) => `${env}: ${ops.join("/")}`).join(" \xB7 ");
+          lines.push(`    resource: ${res.id} \u2014 ${res.title}${bounds ? ` (boundaries \u2014 ${bounds})` : ""}`);
+        } else {
+          lines.push(`    resource: ${t.resource} \u2014 definition not found under knowledge/tech/resources/.`);
+        }
+      }
+    }
+    lines.push(
+      "",
+      "Record what you actually retired as Evidence. Prepare a rollback for every change; for production,",
+      "the rollback/abort path lives in the Runbook, not here."
+    );
+  }
   lines.push(
     "",
     "--- Implementation Plan ---",
@@ -18784,6 +19470,7 @@ function buildImplementationHandoff(dir, workItemId) {
     lifecycle,
     affectedModules,
     resources: wiResources,
+    deprecationTargets: wiDeprecationRefs,
     domains,
     scopeConfidence,
     hasUnmaterializedDecisions: unmaterialized,
@@ -19035,7 +19722,7 @@ function detectFormat(raw) {
   if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
   if (trimmed.startsWith("---")) {
     try {
-      const { data } = matter122(trimmed);
+      const { data } = matter132(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)) {
@@ -19057,7 +19744,7 @@ function parseContent(raw) {
   let bodyText = trimmed;
   if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
     try {
-      const parsed = matter122(trimmed);
+      const parsed = matter132(trimmed);
       frontmatterFields = parsed.data ?? {};
       bodyText = parsed.content.trim();
     } catch {
@@ -19154,7 +19841,7 @@ function findDuplicateByHash(dir, hash) {
     const raw = readFile2(item.filePath);
     if (!raw) continue;
     try {
-      const { data } = matter122(raw);
+      const { data } = matter132(raw);
       const source22 = data?.source;
       if (source22 && typeof source22 === "object" && !Array.isArray(source22)) {
         const s = source22;
@@ -19663,8 +20350,8 @@ async function handleJiraResponse(res) {
   }
   return await res.json();
 }
-async function jiraFetch(baseUrl, path52, auth, timeoutMs, params) {
-  const url = new URL(path52, baseUrl + "/");
+async function jiraFetch(baseUrl, path62, auth, timeoutMs, params) {
+  const url = new URL(path62, baseUrl + "/");
   if (params) for (const [k2, v] of Object.entries(params)) url.searchParams.set(k2, v);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -19682,8 +20369,8 @@ async function jiraFetch(baseUrl, path52, auth, timeoutMs, params) {
     clearTimeout(timer);
   }
 }
-async function jiraPost(baseUrl, path52, auth, timeoutMs, body) {
-  const url = new URL(path52, baseUrl + "/");
+async function jiraPost(baseUrl, path62, auth, timeoutMs, body) {
+  const url = new URL(path62, baseUrl + "/");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -20049,7 +20736,7 @@ function buildInitiativeContent(id, input) {
   if (input.priority) data.priority = input.priority;
   if (input.source) data.source = input.source;
   if (input.sourceId) data.source_id = input.sourceId;
-  return matter14.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
+  return matter15.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
 }
 function createInitiative(dir, input) {
   if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -20073,10 +20760,10 @@ function transitionInitiative(dir, id, to) {
     throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
   }
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter14(raw, {});
+  const { data, content } = matter15(raw, {});
   data.status = to;
   if (to === "completed") data.completed_at = today2();
-  const newContent = matter14.stringify(content, data);
+  const newContent = matter15.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.");
@@ -20086,7 +20773,7 @@ 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 } = matter14(raw, {});
+  const { data, content } = matter15(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);
@@ -20094,7 +20781,7 @@ function addCandidate(dir, id, candidate) {
     throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
   }
   data.candidates = [...existing, candidateToData(normalized)];
-  const newContent = matter14.stringify(content, data);
+  const newContent = matter15.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.");
@@ -20104,7 +20791,7 @@ 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 } = matter14(raw, {});
+  const { data, content } = matter15(raw, {});
   if (patch.title !== void 0) {
     if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
     data.title = patch.title.trim();
@@ -20114,7 +20801,7 @@ function updateInitiative(dir, id, patch) {
   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 = matter14.stringify(content, data);
+  const newContent = matter15.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.");
@@ -20132,10 +20819,10 @@ function addExternalLink(dir, id, link) {
     throw new InitiativeWriteError(`External link ${link.integration}:${link.externalId} already exists on ${id}.`);
   }
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter14(raw, {});
+  const { data, content } = matter15(raw, {});
   const existing = Array.isArray(data.external_links) ? data.external_links : [];
   data.external_links = [...existing, externalLinkToData(link)];
-  const newContent = matter14.stringify(content, data);
+  const newContent = matter15.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.");
@@ -20204,7 +20891,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
     "_What did we learn? Update after completion._",
     ""
   ].join("\n");
-  return matter14.stringify("\n" + body, data);
+  return matter15.stringify("\n" + body, data);
 }
 function materializeCandidate(dir, id, candidateId) {
   const ini = getInitiative(dir, id);
@@ -20221,13 +20908,13 @@ function materializeCandidate(dir, id, candidateId) {
   ensureDir2(join3(dir, DRAFT_DIR));
   writeFile2(join3(dir, DRAFT_DIR, fileName), buildWorkItemContent(wiId, ini.id, candidate));
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter14(raw, {});
+  const { data, content } = matter15(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 = matter14.stringify(content, data);
+  const newContent = matter15.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.");
@@ -20341,7 +21028,7 @@ function evaluateInitiativeCompletion(dir, ini) {
 // ../cli/src/core/resource-write.ts
 import fs6 from "fs";
 import path5 from "path";
-import matter15 from "gray-matter";
+import matter18 from "gray-matter";
 var RESOURCES_DIR = "knowledge/tech/resources";
 var ResourceWriteError = class extends Error {
   constructor(code, message) {
@@ -20421,7 +21108,7 @@ function buildFrontmatter(id, input, base = {}) {
   return data;
 }
 function serialize(data, body) {
-  return matter15.stringify(`
+  return matter18.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -20461,7 +21148,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 = matter15(raw);
+  const parsed = matter18(raw);
   const base = parsed.data ?? {};
   const data = buildFrontmatter(match.id || id, input, base);
   let body = parsed.content.trim();
@@ -20496,6 +21183,355 @@ function deleteResource(dir, id, opts = {}) {
   return { deleted: true, path: match.relPath };
 }
 
+// ../cli/src/core/deprecation-observation.ts
+var DAY_MS2 = 24 * 60 * 60 * 1e3;
+function addDaysIso(startIso, days) {
+  const start = Date.parse(startIso);
+  if (Number.isNaN(start)) return null;
+  return new Date(start + days * DAY_MS2).toISOString().slice(0, 10);
+}
+function observationStatus(target, now = /* @__PURE__ */ new Date()) {
+  const sd = target.softDeprecation;
+  const reasons = [];
+  if (!sd) {
+    return {
+      declared: false,
+      windowElapsed: false,
+      windowEndsAt: null,
+      criteriaTotal: 0,
+      criteriaMet: 0,
+      allCriteriaMet: false,
+      eligibleForRemovalReview: false,
+      reasons: ["No soft-deprecation/observation window declared \u2014 not eligible for removal review."]
+    };
+  }
+  const criteriaTotal = sd.exitCriteria.length;
+  const criteriaMet = sd.exitCriteria.filter((c) => c.met).length;
+  const allCriteriaMet = criteriaTotal > 0 && criteriaMet === criteriaTotal;
+  let windowElapsed = false;
+  let windowEndsAt = null;
+  if (sd.startedAt && sd.observationWindowDays != null) {
+    windowEndsAt = addDaysIso(sd.startedAt, sd.observationWindowDays);
+    if (windowEndsAt) {
+      windowElapsed = now.getTime() >= Date.parse(windowEndsAt);
+    }
+  }
+  if (!sd.startedAt) reasons.push("Observation has not started (no started_at).");
+  else if (sd.observationWindowDays == null) reasons.push("No observation_window_days declared.");
+  else if (!windowElapsed) reasons.push(`Observation window not elapsed (ends ${windowEndsAt ?? "unknown"}).`);
+  if (criteriaTotal === 0) reasons.push("No exit criteria declared.");
+  else if (!allCriteriaMet) reasons.push(`Exit criteria not all met (${criteriaMet}/${criteriaTotal}).`);
+  const eligibleForRemovalReview = windowElapsed && allCriteriaMet;
+  if (eligibleForRemovalReview) {
+    reasons.length = 0;
+    reasons.push("Observation window elapsed and all exit criteria met \u2014 eligible for removal REVIEW (human decision).");
+  }
+  return {
+    declared: true,
+    windowElapsed,
+    windowEndsAt,
+    criteriaTotal,
+    criteriaMet,
+    allCriteriaMet,
+    eligibleForRemovalReview,
+    reasons
+  };
+}
+
+// ../cli/src/core/deprecation-intelligence.ts
+function isStrongNoUsage2(sig) {
+  return sig.status === "no-usage" && (sig.quality === "observed-fact" || sig.quality === "human-confirmed");
+}
+function deriveUnusedConfidence2(evidence) {
+  const present = EVIDENCE_SIGNALS.map((name) => ({ name, sig: evidence[name] })).filter(
+    (e) => Boolean(e.sig)
+  );
+  const usageFound = present.filter((e) => e.sig.status === "usage-found");
+  if (usageFound.length > 0) {
+    return {
+      confidence: "in-use",
+      requiresHumanConfirmation: false,
+      rationale: [`Usage found via: ${usageFound.map((e) => e.name).join(", ")}.`]
+    };
+  }
+  const strong = present.filter((e) => isStrongNoUsage2(e.sig));
+  const unknown = present.filter((e) => e.sig.status === "unknown");
+  const notEvaluated = EVIDENCE_SIGNALS.filter(
+    (name) => !evidence[name] || evidence[name]?.status === "not-evaluated"
+  );
+  const rationale = [];
+  if (strong.length > 0) rationale.push(`No usage observed via: ${strong.map((e) => e.name).join(", ")}.`);
+  if (unknown.length > 0) {
+    rationale.push(`Unknown (looked but could not determine): ${unknown.map((e) => e.name).join(", ")} \u2014 NOT treated as no-usage.`);
+  }
+  if (notEvaluated.length > 0) {
+    rationale.push(`Not evaluated: ${notEvaluated.join(", ")} \u2014 absence of a reference is not evidence of no usage.`);
+  }
+  let confidence;
+  if (strong.length === 0) {
+    confidence = "insufficient-evidence";
+  } else if (unknown.length > 0) {
+    confidence = "medium";
+  } else if (strong.length >= 2) {
+    confidence = "high";
+  } else {
+    confidence = "medium";
+  }
+  return { confidence, requiresHumanConfirmation: true, rationale };
+}
+function deriveRemovalWaves(plan) {
+  const ids = new Set(plan.targets.map((t) => t.id));
+  const deps = /* @__PURE__ */ new Map();
+  const blocked = [];
+  for (const t of plan.targets) {
+    const resolved = [];
+    for (const d3 of t.dependsOnRemoval) {
+      if (d3 === t.id) {
+        blocked.push({ target: t.id, reason: "Target depends on its own removal." });
+        continue;
+      }
+      if (!ids.has(d3)) {
+        blocked.push({ target: t.id, reason: `depends_on_removal references unknown target: ${d3}.` });
+        continue;
+      }
+      resolved.push(d3);
+    }
+    deps.set(t.id, resolved);
+  }
+  const placed = /* @__PURE__ */ new Set();
+  const waves = [];
+  let remaining = plan.targets.map((t) => t.id);
+  while (remaining.length > 0) {
+    const wave = remaining.filter((id) => (deps.get(id) ?? []).every((d3) => placed.has(d3)));
+    if (wave.length === 0) break;
+    for (const id of wave) placed.add(id);
+    waves.push(wave);
+    remaining = remaining.filter((id) => !placed.has(id));
+  }
+  for (const id of remaining) {
+    blocked.push({ target: id, reason: "Involved in a removal dependency cycle \u2014 cannot be ordered." });
+  }
+  return { waves, blocked };
+}
+var RETIRED_STATES = /* @__PURE__ */ new Set([
+  "removed-devtest",
+  "production-changed",
+  "observing",
+  "completed",
+  "deprecated-retained"
+]);
+function isRetiredLifecycle(state) {
+  return RETIRED_STATES.has(state);
+}
+function targetsEligibleForRemoval(plan) {
+  const byId = new Map(plan.targets.map((t) => [t.id, t]));
+  return plan.targets.filter((t) => !isRetiredLifecycle(String(t.lifecycle))).filter(
+    (t) => t.dependsOnRemoval.every((d3) => {
+      const dep = byId.get(d3);
+      return dep ? isRetiredLifecycle(String(dep.lifecycle)) : false;
+    })
+  ).map((t) => t.id);
+}
+function planIntelligence(plan) {
+  const waves = deriveRemovalWaves(plan);
+  const eligible = new Set(targetsEligibleForRemoval(plan));
+  const byId = new Map(plan.targets.map((t) => [t.id, t]));
+  const targets = plan.targets.map((t) => ({
+    id: t.id,
+    unused: deriveUnusedConfidence2(t.usageEvidence),
+    eligibleForRemovalReview: eligible.has(t.id),
+    blockedBy: t.dependsOnRemoval.filter((d3) => {
+      const dep = byId.get(d3);
+      return !dep || !isRetiredLifecycle(String(dep.lifecycle));
+    }),
+    observation: observationStatus(t)
+  }));
+  return { waves, eligible: [...eligible], targets };
+}
+var CANDIDATE_DISCOVERY_GUIDANCE2 = [
+  "Propose deprecation candidates from multiple sources: static references (code/routes/UI/jobs),",
+  "the System Graph (dependencies and blast radius), Legacy Knowledge (risks/unknowns/modernization",
+  "candidates), Project Resources (databases/external systems and their boundaries), runtime evidence",
+  "when telemetry exists, and database metadata when reachable.",
+  "",
+  "Rules:",
+  "- Discovery is a PROPOSAL, not a materialization: never create or retire anything automatically.",
+  "- Always explain WHY something is a candidate, citing the signal(s) observed.",
+  "- Absence of a reference is NOT evidence of no usage. If a source cannot be evaluated, record it",
+  "  as not-evaluated/unknown and require human investigation \u2014 never collapse it to no-usage.",
+  "- A modernization candidate is not automatically a deprecation target.",
+  "- Soft deprecation precedes physical removal; order retirements by dependency, dependents first."
+].join("\n");
+
+// ../cli/src/core/deprecation-write.ts
+import fs7 from "fs";
+import path6 from "path";
+import matter19 from "gray-matter";
+var DeprecationWriteError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DeprecationWriteError";
+  }
+  code;
+};
+function slug5(s) {
+  return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function atomicWrite2(filePath, content) {
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs7.writeFileSync(tmp, content, "utf-8");
+  fs7.renameSync(tmp, filePath);
+}
+function serialize3(data, body) {
+  return matter19.stringify(`
+${body.trim()}
+`, data);
+}
+function allPlanArtifacts(dir) {
+  return discoverKnowledge(dir).filter((a2) => a2.type === DEPRECATION_ARTIFACT_TYPE);
+}
+function nextPlanId(dir, explicit) {
+  if (explicit && explicit.trim()) return explicit.trim();
+  let max = 0;
+  for (const a2 of allPlanArtifacts(dir)) {
+    const m2 = (a2.id || "").match(/^DEP-(\d+)$/i);
+    if (m2) max = Math.max(max, parseInt(m2[1], 10));
+  }
+  return `DEP-${String(max + 1).padStart(3, "0")}`;
+}
+function nextTargetId(targetIds) {
+  let max = 0;
+  for (const id of targetIds) {
+    const m2 = id.match(/^DEP-TGT-(\d+)$/i);
+    if (m2) max = Math.max(max, parseInt(m2[1], 10));
+  }
+  return `DEP-TGT-${String(max + 1).padStart(3, "0")}`;
+}
+function buildTargetRaw(input, base = {}) {
+  const out = { ...base };
+  if (input.id != null) out.id = input.id;
+  if (input.type != null) out.type = input.type;
+  if (input.locator != null) out.locator = input.locator;
+  if (input.title != null) out.title = input.title;
+  if (input.lifecycle != null) out.lifecycle = input.lifecycle;
+  if (input.environments != null) out.environments = input.environments;
+  if (input.assessment != null) {
+    const a2 = { ...typeof base.assessment === "object" && base.assessment ? base.assessment : {} };
+    if (input.assessment.unusedConfidence != null) a2.unused_confidence = input.assessment.unusedConfidence;
+    if (input.assessment.blastRadius != null) a2.blast_radius = input.assessment.blastRadius;
+    if (input.assessment.reversibility != null) a2.reversibility = input.assessment.reversibility;
+    out.assessment = a2;
+  }
+  if (input.dependsOnRemoval != null) out.depends_on_removal = input.dependsOnRemoval;
+  if (input.resource != null) out.resource = input.resource;
+  if (input.module != null) out.module = input.module;
+  return out;
+}
+function validateTargetInput(dir, raw) {
+  const findings = [];
+  const parsed = parseTarget(raw);
+  if (!parsed) {
+    findings.push({ level: "error", message: "A target id is required." });
+    return findings;
+  }
+  for (const f3 of validateTarget(parsed)) {
+    findings.push({ level: f3.severity === "error" ? "error" : "warning", message: f3.message });
+  }
+  const mapped = loadMappedModules(dir).map((m2) => m2.id);
+  if (parsed.module && mapped.length > 0 && !mapped.includes(parsed.module)) {
+    findings.push({ level: "warning", message: `Module "${parsed.module}" is not in .kaddo/modules.yml.` });
+  }
+  if (parsed.resource && !getResource(dir, parsed.resource)) {
+    findings.push({ level: "warning", message: `Project Resource "${parsed.resource}" not found.` });
+  }
+  return findings;
+}
+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 = matter19(readFile(match.filePath));
+  const data = { ...parsed.data ?? {} };
+  return { filePath: match.filePath, data, body: parsed.content.trim() };
+}
+function rawTargets(data) {
+  return Array.isArray(data.targets) ? data.targets : [];
+}
+function createPlan(dir, input) {
+  const title = (input.title ?? "").trim();
+  if (!title) throw new DeprecationWriteError("INVALID_INPUT", "A plan title is required.");
+  const existing = allPlanArtifacts(dir);
+  if (input.id && existing.some((a2) => (a2.id || "").toUpperCase() === input.id.toUpperCase())) {
+    throw new DeprecationWriteError("DUPLICATE", `A plan with id "${input.id}" already exists.`);
+  }
+  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 data = {
+    type: DEPRECATION_ARTIFACT_TYPE,
+    id,
+    title,
+    status: (input.status ?? "draft").trim() || "draft",
+    targets: []
+  };
+  const body = `# Purpose
+
+${(input.purpose ?? "").trim() || "TODO: describe what this plan retires and why."}`;
+  const relPath = `${DEPRECATION_PLANS_DIR}/${id}-${slug5(title) || "plan"}.md`;
+  const filePath = join(dir, relPath);
+  if (exists(filePath)) throw new DeprecationWriteError("DUPLICATE", `Plan file already exists: ${relPath}`);
+  ensureDir(path6.dirname(filePath));
+  atomicWrite2(filePath, serialize3(data, body));
+  return { id, path: relPath, findings: [] };
+}
+function addTarget(dir, planId, input) {
+  const { filePath, data, body } = loadPlanRaw(dir, planId);
+  const targets = rawTargets(data);
+  const existingIds = targets.map((t) => String(t.id ?? ""));
+  const targetId = (input.id ?? "").trim() || nextTargetId(existingIds);
+  if (existingIds.some((id) => id.toUpperCase() === targetId.toUpperCase())) {
+    throw new DeprecationWriteError("DUPLICATE", `Target "${targetId}" already exists in ${planId}.`);
+  }
+  const raw = buildTargetRaw({ ...input, id: targetId, lifecycle: input.lifecycle ?? "candidate" });
+  const findings = validateTargetInput(dir, raw);
+  if (findings.some((f3) => f3.level === "error")) {
+    throw new DeprecationWriteError("VALIDATION_FAILED", findings.filter((f3) => f3.level === "error").map((f3) => f3.message).join("; "));
+  }
+  data.targets = [...targets, raw];
+  atomicWrite2(filePath, serialize3(data, body));
+  return { planId, targetId, path: `${DEPRECATION_PLANS_DIR}/${path6.basename(filePath)}`, findings };
+}
+function updateTarget(dir, planId, targetId, patch) {
+  const { filePath, data, body } = loadPlanRaw(dir, planId);
+  const targets = rawTargets(data);
+  const idx = targets.findIndex((t) => String(t.id ?? "").toUpperCase() === targetId.toUpperCase());
+  if (idx === -1) throw new DeprecationWriteError("NOT_FOUND", `Target "${targetId}" not found in ${planId}.`);
+  const merged = buildTargetRaw({ ...patch, id: String(targets[idx].id) }, targets[idx]);
+  const findings = validateTargetInput(dir, merged);
+  if (findings.some((f3) => f3.level === "error")) {
+    throw new DeprecationWriteError("VALIDATION_FAILED", findings.filter((f3) => f3.level === "error").map((f3) => f3.message).join("; "));
+  }
+  const next = [...targets];
+  next[idx] = merged;
+  data.targets = next;
+  atomicWrite2(filePath, serialize3(data, body));
+  return { planId, targetId: String(targets[idx].id), path: `${DEPRECATION_PLANS_DIR}/${path6.basename(filePath)}`, findings };
+}
+function removeTarget(dir, planId, targetId, opts = {}) {
+  const { filePath, data, body } = loadPlanRaw(dir, planId);
+  const targets = rawTargets(data);
+  const exists3 = targets.some((t) => String(t.id ?? "").toUpperCase() === targetId.toUpperCase());
+  if (!exists3) throw new DeprecationWriteError("NOT_FOUND", `Target "${targetId}" not found in ${planId}.`);
+  const dependents = targets.filter((t) => (Array.isArray(t.depends_on_removal) ? t.depends_on_removal.map(String) : []).some((d3) => d3.toUpperCase() === targetId.toUpperCase())).map((t) => String(t.id));
+  if (!opts.confirm) {
+    return { removed: false, preview: { planId, targetId, dependents } };
+  }
+  data.targets = targets.filter((t) => String(t.id ?? "").toUpperCase() !== targetId.toUpperCase());
+  atomicWrite2(filePath, serialize3(data, body));
+  return { removed: true, path: `${DEPRECATION_PLANS_DIR}/${path6.basename(filePath)}` };
+}
+
 // src/tools.ts
 var ok = (data) => ({ ok: true, data });
 var fail = (message) => ({ ok: false, message });
@@ -20602,12 +21638,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 = matter16(raw);
+  const parsed = matter20(raw);
   const data = { ...parsed.data };
   const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
   data.ready_at = today3;
-  const newContent = matter16.stringify(parsed.content, data);
+  const newContent = matter20.stringify(parsed.content, data);
   const posixPath = item.path.replace(/\\/g, "/");
   let newRelPath = item.path;
   if (posixPath.includes("/work-items/draft/")) {
@@ -20831,11 +21867,78 @@ function deleteResourceTool(root, id, confirm2) {
     return fail(e instanceof ResourceWriteError ? e.message : String(e));
   }
 }
+function listDeprecationsTool(root) {
+  return ok(getDeprecationPlans(root));
+}
+function getDeprecationTool(root, id) {
+  const plan = getDeprecationPlan(root, id);
+  if (!plan) return fail(`Deprecation Plan "${id}" not found.`);
+  return ok(plan);
+}
+function planDeprecationTool(root, id) {
+  const plan = getDeprecationPlan(root, id);
+  if (!plan) return fail(`Deprecation Plan "${id}" not found.`);
+  return ok(deriveRemovalWaves(plan));
+}
+function analyzeDeprecationTool(root, id) {
+  const plan = getDeprecationPlan(root, id);
+  if (!plan) return fail(`Deprecation Plan "${id}" not found.`);
+  return ok(planIntelligence(plan));
+}
+function createDeprecationTool(root, args, confirm2) {
+  if (!confirm2) {
+    return ok({ status: "needs_confirmation", action: "create", proposal: args, message: "Re-call with confirm=true to create this Deprecation Plan." });
+  }
+  try {
+    return ok({ status: "created", ...createPlan(root, args) });
+  } catch (e) {
+    return fail(e instanceof DeprecationWriteError ? e.message : String(e));
+  }
+}
+function addDeprecationTargetTool(root, planId, args, confirm2) {
+  if (!getDeprecationPlan(root, planId)) return fail(`Deprecation Plan "${planId}" not found.`);
+  if (!confirm2) {
+    const findings = validateTargetInput(root, { ...args, id: args.id ?? "DEP-TGT-NEW", lifecycle: args.lifecycle ?? "candidate" });
+    return ok({ status: "needs_confirmation", action: "add_target", planId, proposal: args, findings, message: "Re-call with confirm=true to add this target." });
+  }
+  try {
+    return ok({ status: "added", ...addTarget(root, planId, args) });
+  } catch (e) {
+    return fail(e instanceof DeprecationWriteError ? e.message : String(e));
+  }
+}
+function updateDeprecationTargetTool(root, planId, targetId, args, confirm2) {
+  if (!getDeprecationPlan(root, planId)) return fail(`Deprecation Plan "${planId}" not found.`);
+  if (!confirm2) {
+    return ok({ status: "needs_confirmation", action: "update_target", planId, targetId, changes: args, message: "Re-call with confirm=true to apply this update." });
+  }
+  try {
+    return ok({ status: "updated", ...updateTarget(root, planId, targetId, args) });
+  } catch (e) {
+    return fail(e instanceof DeprecationWriteError ? e.message : String(e));
+  }
+}
+function removeDeprecationTargetTool(root, planId, targetId, confirm2) {
+  if (!getDeprecationPlan(root, planId)) return fail(`Deprecation Plan "${planId}" not found.`);
+  if (!confirm2) {
+    try {
+      const preview = removeTarget(root, planId, targetId);
+      return ok({ status: "needs_confirmation", action: "remove_target", ...preview.preview, message: "Re-call with confirm=true to remove. Dependents\u2019 depends_on_removal are NOT rewritten." });
+    } catch (e) {
+      return fail(e instanceof DeprecationWriteError ? e.message : String(e));
+    }
+  }
+  try {
+    return ok({ status: "removed", ...removeTarget(root, planId, targetId, { confirm: true }) });
+  } catch (e) {
+    return fail(e instanceof DeprecationWriteError ? e.message : String(e));
+  }
+}
 
 // src/multirepo.ts
-import fs7 from "fs";
-import path6 from "path";
-import matter17 from "gray-matter";
+import fs8 from "fs";
+import path7 from "path";
+import matter21 from "gray-matter";
 import { parse as parseYaml11, stringify as stringifyYaml8 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
@@ -20855,24 +21958,24 @@ function isCore2(config) {
   return projectRole2(config) === "core";
 }
 function readModuleFile(root, repoPath, relFile) {
-  const moduleDir = path6.resolve(root, repoPath);
-  const abs = path6.resolve(moduleDir, relFile);
+  const moduleDir = path7.resolve(root, repoPath);
+  const abs = path7.resolve(moduleDir, relFile);
   if (!abs.startsWith(moduleDir)) return null;
-  if (!fs7.existsSync(abs) || !fs7.statSync(abs).isFile()) return null;
-  return fs7.readFileSync(abs, "utf-8");
+  if (!fs8.existsSync(abs) || !fs8.statSync(abs).isFile()) return null;
+  return fs8.readFileSync(abs, "utf-8");
 }
 function detectModuleStatus2(root, repoPath) {
-  const moduleDir = path6.resolve(root, repoPath);
-  if (!fs7.existsSync(moduleDir)) {
+  const moduleDir = path7.resolve(root, repoPath);
+  if (!fs8.existsSync(moduleDir)) {
     return { status: "missing", configured: false, moduleContext: false, currentState: false, codebase: false, warning: `Directory \`${repoPath}\` does not exist.` };
   }
-  const configPath = path6.join(moduleDir, ".kaddo", "config.yml");
-  if (!fs7.existsSync(configPath)) {
+  const configPath = path7.join(moduleDir, ".kaddo", "config.yml");
+  if (!fs8.existsSync(configPath)) {
     return { status: "not_configured", configured: false, moduleContext: false, currentState: false, codebase: false, warning: `Run \`kaddo init\` inside \`${repoPath}\` and select multirepo \u2192 module.` };
   }
   let parsed = null;
   try {
-    parsed = parseYaml11(fs7.readFileSync(configPath, "utf-8"));
+    parsed = parseYaml11(fs8.readFileSync(configPath, "utf-8"));
   } catch {
   }
   const role = parsed?.project?.role ?? parsed?.multirepo?.role;
@@ -20883,14 +21986,14 @@ function detectModuleStatus2(root, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: fs7.existsSync(path6.join(moduleDir, "knowledge", "tech", "module", "module-context.md")) || fs7.existsSync(path6.join(moduleDir, "knowledge", "module", "module-context.md")),
-    currentState: fs7.existsSync(path6.join(moduleDir, "knowledge", "tech", "current-state.md")),
-    codebase: fs7.existsSync(path6.join(moduleDir, "knowledge", "tech", "codebase.md"))
+    moduleContext: fs8.existsSync(path7.join(moduleDir, "knowledge", "tech", "module", "module-context.md")) || fs8.existsSync(path7.join(moduleDir, "knowledge", "module", "module-context.md")),
+    currentState: fs8.existsSync(path7.join(moduleDir, "knowledge", "tech", "current-state.md")),
+    codebase: fs8.existsSync(path7.join(moduleDir, "knowledge", "tech", "codebase.md"))
   };
 }
 function resolveModuleContextPath(root, repoPath) {
-  const moduleDir = path6.resolve(root, repoPath);
-  if (fs7.existsSync(path6.join(moduleDir, "knowledge", "tech", "module", "module-context.md"))) {
+  const moduleDir = path7.resolve(root, repoPath);
+  if (fs8.existsSync(path7.join(moduleDir, "knowledge", "tech", "module", "module-context.md"))) {
     return "knowledge/tech/module/module-context.md";
   }
   return "knowledge/module/module-context.md";
@@ -20987,7 +22090,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 = matter17(raw);
+  const parsed = matter21(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) : [] })) : [];
@@ -21040,7 +22143,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 = matter17(raw);
+  const parsed = matter21(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) : [] })) : [];
@@ -21094,15 +22197,15 @@ function extractSection(content, heading) {
   return out;
 }
 function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
-  const slug6 = slugify4(wi.title);
+  const slug7 = slugify4(wi.title);
   const wiLower = wi.id.toLowerCase();
-  const coreBranch = `feature/${wiLower}-${slug6}`;
+  const coreBranch = `feature/${wiLower}-${slug7}`;
   const moduleBranches = {};
   const commitMessages = {};
   for (const modId of affectedModules) {
     const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
     const repo = mod ? moduleRepoPath(mod) || modId : modId;
-    moduleBranches[repo] = `feature/${wiLower}-${modId}-${slug6.slice(0, 20)}`;
+    moduleBranches[repo] = `feature/${wiLower}-${modId}-${slug7.slice(0, 20)}`;
     commitMessages[repo] = `fix(${wiLower}): update ${modId}`;
   }
   commitMessages["core"] = `docs(${wiLower}): capture cross-repo implementation summary`;
@@ -21126,7 +22229,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 = matter17(raw);
+  const parsed = matter21(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) : [] })) : [];
@@ -21275,31 +22378,31 @@ function modulesDiscoverTool(root, args) {
   const sysName = config.system?.name ?? config.project?.name ?? "";
   const workspaceRoots2 = config.multirepo?.workspace_roots ?? [".."];
   const IGNORED = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "coverage", "vendor", ".next", "out", "tmp", "temp", ".kaddo"]);
-  const coreAbs = path6.resolve(root);
+  const coreAbs = path7.resolve(root);
   const discovered = [];
   for (const wr of workspaceRoots2) {
-    const rootAbs = path6.resolve(root, wr);
-    if (!fs7.existsSync(rootAbs) || !fs7.statSync(rootAbs).isDirectory()) continue;
+    const rootAbs = path7.resolve(root, wr);
+    if (!fs8.existsSync(rootAbs) || !fs8.statSync(rootAbs).isDirectory()) continue;
     let entries;
     try {
-      entries = fs7.readdirSync(rootAbs);
+      entries = fs8.readdirSync(rootAbs);
     } catch {
       continue;
     }
     for (const entry of entries) {
       if (IGNORED.has(entry)) continue;
-      const candidateAbs = path6.resolve(rootAbs, entry);
-      if (!fs7.statSync(candidateAbs).isDirectory()) continue;
+      const candidateAbs = path7.resolve(rootAbs, entry);
+      if (!fs8.statSync(candidateAbs).isDirectory()) continue;
       if (candidateAbs === coreAbs) continue;
-      const relPath = path6.relative(root, candidateAbs).replace(/\\/g, "/");
-      const cfgPath = path6.join(candidateAbs, ".kaddo", "config.yml");
-      if (!fs7.existsSync(cfgPath)) {
+      const relPath = path7.relative(root, candidateAbs).replace(/\\/g, "/");
+      const cfgPath = path7.join(candidateAbs, ".kaddo", "config.yml");
+      if (!fs8.existsSync(cfgPath)) {
         discovered.push({ id: entry, path: relPath, status: "not_configured", eligibleForMapping: false });
         continue;
       }
       let parsed = null;
       try {
-        parsed = parseYaml11(fs7.readFileSync(cfgPath, "utf-8"));
+        parsed = parseYaml11(fs8.readFileSync(cfgPath, "utf-8"));
       } catch {
       }
       const role = parsed?.project?.role ?? parsed?.multirepo?.role;
@@ -21373,8 +22476,8 @@ ${list3(data.owners)}
 
 // ../cli/src/core/system-topology.ts
 import { parse as parseYaml12, stringify as stringifyYaml9 } from "yaml";
-import fs8 from "fs";
-import path7 from "path";
+import fs9 from "fs";
+import path8 from "path";
 import crypto from "crypto";
 var TOPOLOGY_FILE2 = "knowledge/tech/system-topology.yml";
 var SYSTEM_ENTITY_KINDS2 = /* @__PURE__ */ new Set([
@@ -21746,16 +22849,16 @@ function findSystemPaths(dir, source3, target, opts = {}) {
     out.get(r2.source).push(r2.target);
   }
   const paths = [];
-  const walk = (node, path9) => {
+  const walk = (node, path10) => {
     if (paths.length >= 20) return;
-    if (node === target && path9.length > 1) {
-      paths.push([...path9]);
+    if (node === target && path10.length > 1) {
+      paths.push([...path10]);
       return;
     }
-    if (path9.length > maxDepth) return;
+    if (path10.length > maxDepth) return;
     for (const nxt of out.get(node) ?? []) {
-      if (path9.includes(nxt)) continue;
-      walk(nxt, [...path9, nxt]);
+      if (path10.includes(nxt)) continue;
+      walk(nxt, [...path10, nxt]);
     }
   };
   walk(source3, [source3]);
@@ -21780,14 +22883,14 @@ function getImpactCandidates(dir, seedIds, opts = {}) {
         existing.reason.push(reason);
         continue;
       }
-      const path9 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
+      const path10 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
       candidates.set(n.id, {
         nodeId: n.id,
         label: n.label,
         kind: n.type,
         ...n.moduleId ? { moduleId: n.moduleId } : {},
         reason: [reason],
-        ...path9 ? { graphPath: path9.map((id) => byId.get(id)?.label ?? id) } : {},
+        ...path10 ? { graphPath: path10.map((id) => byId.get(id)?.label ?? id) } : {},
         ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
         ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
         status: "candidate",
@@ -21886,14 +22989,14 @@ function systemImpactCandidatesTool(root, args) {
 }
 
 // ../cli/src/services/integrations.ts
-import matter19 from "gray-matter";
+import matter24 from "gray-matter";
 import { parse as parseYaml13, stringify as stringifyYaml10 } from "yaml";
 
 // ../cli/src/core/work-item-write.ts
-import fs9 from "fs";
-import path8 from "path";
+import fs10 from "fs";
+import path9 from "path";
 import crypto4 from "crypto";
-import matter18 from "gray-matter";
+import matter23 from "gray-matter";
 var SECTION_ORDER2 = [
   "Actor",
   "Outcome",
@@ -22561,8 +23664,8 @@ async function handleJiraResponse2(res) {
   }
   return await res.json();
 }
-async function jiraFetch2(baseUrl, path9, auth, timeoutMs, params) {
-  const url = new URL(path9, baseUrl + "/");
+async function jiraFetch2(baseUrl, path10, auth, timeoutMs, params) {
+  const url = new URL(path10, baseUrl + "/");
   if (params) for (const [k2, v] of Object.entries(params)) url.searchParams.set(k2, v);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -22580,8 +23683,8 @@ async function jiraFetch2(baseUrl, path9, auth, timeoutMs, params) {
     clearTimeout(timer);
   }
 }
-async function jiraPost2(baseUrl, path9, auth, timeoutMs, body) {
-  const url = new URL(path9, baseUrl + "/");
+async function jiraPost2(baseUrl, path10, auth, timeoutMs, body) {
+  const url = new URL(path10, baseUrl + "/");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -22941,7 +24044,7 @@ async function integrationsWorkItemTool(root, args) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter20 from "gray-matter";
+import matter25 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR4 = "knowledge";
 function readScanJson(dir) {
@@ -22954,7 +24057,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph4(markdown) {
-  const body = matter20(markdown).content.trim();
+  const body = matter25(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -23946,7 +25049,7 @@ function requireKnowledge(root) {
     throw new KaddoMcpError("Knowledge repository not found. Run `kaddo bootstrap` first.");
   }
 }
-function slug5(s) {
+function slug6(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 }
 function generateContext(root) {
@@ -24079,7 +25182,7 @@ function generateCapsuleDraft(root) {
   const config = requireConfig(root);
   requireKnowledge(root);
   const capsule = buildCapsule(root, config);
-  const name = slug5(config.project.name);
+  const name = slug6(config.project.name);
   const md = `.kaddo/exports/${name}.capsule.md`;
   const json = `.kaddo/exports/${name}.capsule.json`;
   writeDerived(root, md, renderCapsuleMarkdown(capsule));
@@ -24442,6 +25545,74 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => deleteResourceTool(root, args.id, args.confirm)))
   );
+  server.registerTool(
+    "kaddo_list_deprecations",
+    { title: "List Deprecation Plans", description: "List Controlled Deprecation Plans under knowledge/legacy/deprecations/ (read-only).", inputSchema: {} },
+    async () => toolText(guarded(root, () => listDeprecationsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_deprecation",
+    { title: "Get Deprecation Plan", description: "Get one Deprecation Plan by ID: purpose, typed targets, lifecycle and per-environment state.", inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getDeprecationTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_plan_deprecation",
+    { title: "Deprecation Removal Waves", description: "Derive the dependency-ordered removal waves (dependents first) and blocked targets for a plan. Explainable, not a manual priority.", inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => planDeprecationTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_analyze_deprecation",
+    { title: "Analyze Deprecation Plan", description: "Per-target unused-confidence from usage evidence + removal eligibility. Absence of a reference is never treated as no-usage; removal always requires human confirmation.", inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => analyzeDeprecationTool(root, args.id)))
+  );
+  const targetFields = {
+    id: z4.string().optional(),
+    type: z4.string().optional(),
+    locator: z4.string().optional(),
+    title: z4.string().optional(),
+    lifecycle: z4.string().optional(),
+    environments: z4.record(z4.string()).optional(),
+    assessment: z4.object({ unusedConfidence: z4.string().optional(), blastRadius: z4.string().optional(), reversibility: z4.string().optional() }).optional(),
+    dependsOnRemoval: z4.array(z4.string()).optional(),
+    resource: z4.string().optional(),
+    module: z4.string().optional()
+  };
+  server.registerTool(
+    "kaddo_create_deprecation",
+    {
+      title: "Create Deprecation Plan",
+      description: "Propose creating a Deprecation Plan. Without confirm, returns a preview (writes nothing); with confirm=true, Core persists it as Markdown.",
+      inputSchema: { title: z4.string().optional(), purpose: z4.string().optional(), status: z4.string().optional(), confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => createDeprecationTool(root, args, args.confirm)))
+  );
+  server.registerTool(
+    "kaddo_add_deprecation_target",
+    {
+      title: "Add Deprecation Target",
+      description: "Propose adding a typed target to a plan. Without confirm, returns a preview + validation findings; with confirm=true, Core appends it (no-lossy).",
+      inputSchema: { planId: z4.string(), ...targetFields, confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => addDeprecationTargetTool(root, args.planId, args, args.confirm)))
+  );
+  server.registerTool(
+    "kaddo_update_deprecation_target",
+    {
+      title: "Update Deprecation Target",
+      description: "Propose updating a target in place (no-lossy). Without confirm, returns a preview; with confirm=true, Core applies it.",
+      inputSchema: { planId: z4.string(), targetId: z4.string(), ...targetFields, confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => updateDeprecationTargetTool(root, args.planId, args.targetId, args, args.confirm)))
+  );
+  server.registerTool(
+    "kaddo_remove_deprecation_target",
+    {
+      title: "Remove Deprecation Target",
+      description: "Remove a target. Without confirm, returns what depends on it (writes nothing); with confirm=true, Core removes it \u2014 dependents\u2019 depends_on_removal are left intact.",
+      inputSchema: { planId: z4.string(), targetId: z4.string(), confirm: z4.boolean().optional() }
+    },
+    async (args) => toolText(guarded(root, () => removeDeprecationTargetTool(root, args.planId, args.targetId, args.confirm)))
+  );
   server.registerTool(
     "kaddo_list_capsules",
     { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },