@kaddo/mcp 3.113.0 → 3.115.0

package/dist/index.js

@@ -386,7 +386,7 @@ function join(...parts) {
 }
 
 // ../cli/src/core/impact-report.ts
-import matter9 from "gray-matter";
+import matter10 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
@@ -2590,8 +2590,117 @@ function discoverInitiatives(dir) {
   return out.sort((a2, b2) => a2.id.localeCompare(b2.id));
 }
 
+// ../cli/src/core/resources.ts
+import matter6 from "gray-matter";
+var RESOURCE_ARTIFACT_TYPE = "project-resource";
+function str(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function strArray(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 parseInterfaces(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (!raw || typeof raw !== "object") continue;
+    const o2 = raw;
+    const type = str(o2.type);
+    if (!type) continue;
+    out.push({
+      type,
+      tool: str(o2.tool),
+      provider: str(o2.provider),
+      purpose: str(o2.purpose),
+      operations: strArray(o2.operations),
+      environments: strArray(o2.environments),
+      constraints: str(o2.constraints)
+    });
+  }
+  return out;
+}
+function parseBoundaries(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const out = {};
+  for (const [env, val] of Object.entries(v)) {
+    const list3 = strArray(val);
+    if (list3.length > 0) out[env] = list3;
+  }
+  return out;
+}
+function parseAuth(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return { mode: null, refs: [] };
+  const o2 = v;
+  const refs = strArray(o2.refs).filter((r2) => !r2.includes("=") && /^[A-Za-z0-9_.-]+$/.test(r2));
+  return { mode: str(o2.mode), refs };
+}
+function toDetail(filePath, relPath, raw) {
+  const parsed = matter6(raw);
+  const fm = parsed.data ?? {};
+  const body = parsed.content.trim();
+  const id = str(fm.id) ?? "";
+  return {
+    id,
+    title: str(fm.title) ?? id,
+    resourceType: str(fm.resource_type),
+    provider: str(fm.provider),
+    environments: strArray(fm.environments),
+    path: relPath,
+    purpose: str(fm.purpose),
+    interfaces: parseInterfaces(fm.access_interfaces),
+    boundaries: parseBoundaries(fm.access_boundaries),
+    ...(() => {
+      const a2 = parseAuth(fm.authentication);
+      return { authRefs: a2.refs, authMode: a2.mode };
+    })(),
+    markdownBody: body
+  };
+}
+function getResources(dir) {
+  return discoverKnowledge(dir).filter((a2) => a2.type === RESOURCE_ARTIFACT_TYPE).map((a2) => {
+    const fm = a2.rawFrontmatter;
+    return {
+      id: a2.id || str(fm.id) || a2.title,
+      title: a2.title || str(fm.title) || a2.id,
+      resourceType: str(fm.resource_type),
+      provider: str(fm.provider),
+      environments: strArray(fm.environments),
+      path: a2.relPath
+    };
+  }).sort((x2, y) => x2.id.localeCompare(y.id));
+}
+function getResource(dir, id) {
+  const match = discoverKnowledge(dir).find(
+    (a2) => a2.type === RESOURCE_ARTIFACT_TYPE && (a2.id === id || a2.title === id)
+  );
+  if (!match) return null;
+  const raw = readFile(match.filePath);
+  return toDetail(match.filePath, match.relPath, raw);
+}
+function parseWorkItemResources(fm) {
+  const v = fm.resources;
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o2 = raw;
+    const id = str(o2.id);
+    if (!id) continue;
+    out.push({ id, role: str(o2.role) ?? "affected" });
+  }
+  return out;
+}
+
 // ../cli/src/core/graph.ts
 var KNOWLEDGE3 = "knowledge";
+var RESOURCE_ROLE_EDGE = {
+  affected: "affects",
+  implementation: "uses",
+  validation: "validates_with",
+  delivery: "delivers_through"
+};
 var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
 var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
 function scopeStatuses(scope) {
@@ -2670,6 +2779,16 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       if (cand.materializedAs) addEdge(candId, `wi:${cand.materializedAs}`, "materialized_as");
     }
   }
+  const resourceTitleById = /* @__PURE__ */ new Map();
+  for (const r2 of getResources(dir)) {
+    resourceTitleById.set(r2.id, r2.title);
+    addNode({
+      id: `resource:${r2.id}`,
+      type: "project-resource",
+      label: r2.title ? `${r2.id} ${r2.title}`.trim() : r2.id,
+      path: r2.path
+    });
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -2694,6 +2813,12 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addNode({ id: capId, type: "capability", label: cap });
       addEdge(wiNodeId, capId, "implements");
     }
+    for (const rel of parseWorkItemResources(wi.rawFrontmatter)) {
+      const resId = `resource:${rel.id}`;
+      const title = resourceTitleById.get(rel.id);
+      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 dec of wi.decisions) {
       if (!dec || !dec.trim()) continue;
       const adrId = `adr:${dec}`;
@@ -3072,7 +3197,7 @@ function loadGraphHints(dir) {
 }
 
 // ../cli/src/services/installed-skills.ts
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 var SKILLS_DIR = join("knowledge", "skills");
 function discoverInstalledSkills(dir) {
   const base = join(dir, SKILLS_DIR);
@@ -3082,7 +3207,7 @@ function discoverInstalledSkills(dir) {
     const skillFile = join(base, entry, "skill.md");
     if (!isFile(skillFile)) continue;
     try {
-      const { data } = matter6(readFile(skillFile));
+      const { data } = matter7(readFile(skillFile));
       if (data.type && String(data.type) !== "skill") continue;
       const id = String(data.id ?? entry);
       out.push({
@@ -4671,7 +4796,7 @@ function deriveDeliveryCompletedStatus(dir) {
 }
 
 // ../cli/src/core/assets.ts
-import matter7 from "gray-matter";
+import matter8 from "gray-matter";
 
 // ../cli/src/core/version.ts
 import { fileURLToPath } from "url";
@@ -4826,8 +4951,13 @@ dependencies.
    flags, content/copy, authentication/authorization, notifications, analytics, documentation,
    operations/release \u2014 as affected, reviewed-not-affected, unknown, or not-applicable.
 4. **Module review** \u2014 for multirepo, evaluate each mapped module with the same statuses.
-5. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, unknowns
-   visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
+5. **Resource review** \u2014 ask: does this change need to observe, modify, validate or deliver against a
+   known external resource of the project (a Project Resource under \`knowledge/tech/resources/\` \u2014
+   database, cloud, API, queue, storage\u2026)? If so, declare it in the WI front matter \`resources:\` with
+   a role (\`affected\`, \`implementation\`, \`validation\`, \`delivery\`). Resources are external systems,
+   distinct from \`affected_modules\` (code). Not every WI needs resources (e.g. a CSS change does not).
+6. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, resources
+   assessed, unknowns visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
 
 ## Rules
 
@@ -4838,6 +4968,8 @@ dependencies.
 - Include at least one end-to-end acceptance criterion for user-facing changes.
 - Do not reduce a product intent to the first technical implementation found.
 - Evaluate surfaces and modules before proposing files.
+- Consider Project Resources when the scope justifies it; never invent resources not backed by
+  project knowledge, and keep \`resources\` (external systems) separate from \`affected_modules\` (code).
 - This skill refines scope and acceptance criteria but does not approve implementation readiness.
   Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
 
@@ -7877,7 +8009,7 @@ function canonicalSkills() {
 }
 function versionOf(content) {
   try {
-    const v = matter7(content).data.version;
+    const v = matter8(content).data.version;
     return v === void 0 || v === null ? null : String(v);
   } catch {
     return null;
@@ -8649,7 +8781,7 @@ function renderRouteCompact(route) {
 }
 
 // ../cli/src/core/metadata-health.ts
-import matter8 from "gray-matter";
+import matter9 from "gray-matter";
 var KNOWLEDGE_FILES2 = [
   "knowledge/business/business.md",
   "knowledge/product/product.md",
@@ -8669,7 +8801,7 @@ function analyzeMetadataHealth(dir) {
     let data;
     try {
       const raw = readFile(p);
-      data = matter8(raw).data;
+      data = matter9(raw).data;
     } catch {
       continue;
     }
@@ -8701,7 +8833,7 @@ function analyzeMetadataHealth(dir) {
         if (isFile(p) && entry.endsWith(".md")) {
           try {
             const raw = readFile(p);
-            const fm = matter8(raw).data;
+            const fm = matter9(raw).data;
             if (fm.status === "done") {
               const rel = p.replace(dir + "/", "").replace(dir + "\\", "").replace(/\\/g, "/");
               findings.push({
@@ -9656,7 +9788,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter9(readFile(wi.filePath)).content;
+      const body = matter10(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++;
@@ -10369,7 +10501,7 @@ function serializeDriftJson(r2) {
 }
 
 // src/workitems.ts
-import matter10 from "gray-matter";
+import matter11 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;
@@ -10392,7 +10524,7 @@ function parseSource(data) {
   return { type: "unknown", inferred: true };
 }
 var ACTIVE_STATES2 = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
-function strArray(v) {
+function strArray2(v) {
   return Array.isArray(v) ? v.map((x2) => String(x2)).filter(Boolean) : [];
 }
 function lifecycleOf(data, relPath) {
@@ -10460,15 +10592,15 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter10(raw);
+      parsed = matter11(raw);
     } catch {
       continue;
     }
     const data = parsed.data;
     if (!data.type) continue;
     const status = lifecycleOf(data, rel);
-    const code = strArray(data.code);
-    const domains = strArray(data.domains);
+    const code = strArray2(data.code);
+    const domains = strArray2(data.domains);
     const source = parseSource(data);
     const readiness = status === "draft" ? assessReadiness(data, parsed.content, code, domains, source) : void 0;
     items.push({
@@ -10480,9 +10612,9 @@ function listWorkItems(root) {
       path: rel,
       summary: String(data.summary ?? "") || firstParagraph2(parsed.content),
       code,
-      capabilities: strArray(data.capabilities),
-      decisions: strArray(data.decisions),
-      capsules: strArray(data.capsules),
+      capabilities: strArray2(data.capabilities),
+      decisions: strArray2(data.decisions),
+      capsules: strArray2(data.capsules),
       source,
       domains,
       readiness,
@@ -10928,14 +11060,14 @@ function getPrompt(root, name) {
 }
 
 // src/tools.ts
-import matter12 from "gray-matter";
+import matter13 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 } from "yaml";
-import matter11 from "gray-matter";
+import matter12 from "gray-matter";
 import matter22 from "gray-matter";
 import { parse as parseYaml62, stringify as stringifyYaml32 } from "yaml";
 import { parse as parseYaml22 } from "yaml";
@@ -10944,25 +11076,26 @@ import { parse as parseYaml52, stringify as stringifyYaml22 } from "yaml";
 import { parse as parseYaml42, stringify as stringifyYaml4 } from "yaml";
 import matter32 from "gray-matter";
 import matter42 from "gray-matter";
-import { parse as parseYaml72 } from "yaml";
 import matter52 from "gray-matter";
+import { parse as parseYaml72 } from "yaml";
+import matter62 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 matter62 from "gray-matter";
 import matter72 from "gray-matter";
+import matter82 from "gray-matter";
 import { parse as parseYaml82, stringify as stringifyYaml42 } from "yaml";
 import fs32 from "fs";
 import path32 from "path";
 import crypto2 from "crypto";
-import matter82 from "gray-matter";
+import matter92 from "gray-matter";
 import crypto3 from "crypto";
 import fs4 from "fs";
-import matter92 from "gray-matter";
 import matter102 from "gray-matter";
+import matter112 from "gray-matter";
 import { parse as parseYaml92, stringify as stringifyYaml5 } from "yaml";
 import { parse as parseYaml102, stringify as stringifyYaml6 } from "yaml";
-import matter112 from "gray-matter";
+import matter122 from "gray-matter";
 function exists2(p) {
   return fs3.existsSync(p);
 }
@@ -11130,7 +11263,7 @@ function parseImpactAnalysis2(data) {
 }
 function parseArtifact2(filePath, raw) {
   try {
-    const { data } = matter11(raw);
+    const { data } = matter12(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -12684,7 +12817,113 @@ function suggestInitiativesForExternalItem(dir, integration, externalId) {
     )
   );
 }
+var RESOURCE_ARTIFACT_TYPE2 = "project-resource";
+function str2(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function strArray3(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 parseInterfaces2(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (!raw || typeof raw !== "object") continue;
+    const o2 = raw;
+    const type = str2(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)
+    });
+  }
+  return out;
+}
+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);
+    if (list22.length > 0) out[env] = list22;
+  }
+  return out;
+}
+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 };
+}
+function toDetail2(filePath, relPath, raw) {
+  const parsed = matter42(raw);
+  const fm = parsed.data ?? {};
+  const body = parsed.content.trim();
+  const id = str2(fm.id) ?? "";
+  return {
+    id,
+    title: str2(fm.title) ?? id,
+    resourceType: str2(fm.resource_type),
+    provider: str2(fm.provider),
+    environments: strArray3(fm.environments),
+    path: relPath,
+    purpose: str2(fm.purpose),
+    interfaces: parseInterfaces2(fm.access_interfaces),
+    boundaries: parseBoundaries2(fm.access_boundaries),
+    ...(() => {
+      const a2 = parseAuth2(fm.authentication);
+      return { authRefs: a2.refs, authMode: a2.mode };
+    })(),
+    markdownBody: body
+  };
+}
+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),
+      path: a2.relPath
+    };
+  }).sort((x2, y) => x2.id.localeCompare(y.id));
+}
+function getResource2(dir, id) {
+  const match = discoverKnowledge2(dir).find(
+    (a2) => a2.type === RESOURCE_ARTIFACT_TYPE2 && (a2.id === id || a2.title === id)
+  );
+  if (!match) return null;
+  const raw = readFile2(match.filePath);
+  return toDetail2(match.filePath, match.relPath, raw);
+}
+function parseWorkItemResources2(fm) {
+  const v = fm.resources;
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const raw of v) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const o2 = raw;
+    const id = str2(o2.id);
+    if (!id) continue;
+    out.push({ id, role: str2(o2.role) ?? "affected" });
+  }
+  return out;
+}
 var KNOWLEDGE22 = "knowledge";
+var RESOURCE_ROLE_EDGE2 = {
+  affected: "affects",
+  implementation: "uses",
+  validation: "validates_with",
+  delivery: "delivers_through"
+};
 var ACTIVE_STATUSES2 = ["draft", "ready", "in-progress", "blocked"];
 var ALL_STATUSES2 = ["draft", "ready", "in-progress", "blocked", "completed"];
 function scopeStatuses2(scope) {
@@ -12763,6 +13002,16 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       if (cand.materializedAs) addEdge(candId, `wi:${cand.materializedAs}`, "materialized_as");
     }
   }
+  const resourceTitleById = /* @__PURE__ */ new Map();
+  for (const r2 of getResources2(dir)) {
+    resourceTitleById.set(r2.id, r2.title);
+    addNode({
+      id: `resource:${r2.id}`,
+      type: "project-resource",
+      label: r2.title ? `${r2.id} ${r2.title}`.trim() : r2.id,
+      path: r2.path
+    });
+  }
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     if (!id || !id.trim()) continue;
@@ -12787,6 +13036,12 @@ function buildGraph2(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       addNode({ id: capId, type: "capability", label: cap });
       addEdge(wiNodeId, capId, "implements");
     }
+    for (const rel of parseWorkItemResources2(wi.rawFrontmatter)) {
+      const resId = `resource:${rel.id}`;
+      const title = resourceTitleById.get(rel.id);
+      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 dec of wi.decisions) {
       if (!dec || !dec.trim()) continue;
       const adrId = `adr:${dec}`;
@@ -13280,8 +13535,13 @@ dependencies.
    flags, content/copy, authentication/authorization, notifications, analytics, documentation,
    operations/release \u2014 as affected, reviewed-not-affected, unknown, or not-applicable.
 4. **Module review** \u2014 for multirepo, evaluate each mapped module with the same statuses.
-5. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, unknowns
-   visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
+5. **Resource review** \u2014 ask: does this change need to observe, modify, validate or deliver against a
+   known external resource of the project (a Project Resource under \`knowledge/tech/resources/\` \u2014
+   database, cloud, API, queue, storage\u2026)? If so, declare it in the WI front matter \`resources:\` with
+   a role (\`affected\`, \`implementation\`, \`validation\`, \`delivery\`). Resources are external systems,
+   distinct from \`affected_modules\` (code). Not every WI needs resources (e.g. a CSS change does not).
+6. **Completeness review** \u2014 confirm: outcome covered, journey covered, modules assessed, resources
+   assessed, unknowns visible, acceptance criteria end-to-end, scope and out-of-scope coherent.
 
 ## Rules
 
@@ -13292,6 +13552,8 @@ dependencies.
 - Include at least one end-to-end acceptance criterion for user-facing changes.
 - Do not reduce a product intent to the first technical implementation found.
 - Evaluate surfaces and modules before proposing files.
+- Consider Project Resources when the scope justifies it; never invent resources not backed by
+  project knowledge, and keep \`resources\` (external systems) separate from \`affected_modules\` (code).
 - This skill refines scope and acceptance criteria but does not approve implementation readiness.
   Readiness requires human confirmation through \`kaddo ready\` or the MCP \`mark_work_item_ready\` action.
 
@@ -16979,6 +17241,8 @@ function getWorkItem(dir, workItemId) {
     path: match.relPath,
     // Faithful source of truth: the artifact body already read above, not reconstructed (WI-025).
     markdownBody: body.trim(),
+    // External systems this WI relates to (WI-030), separate from affectedModules (code).
+    resources: parseWorkItemResources2(fm),
     ...parseSystemImpact(dir, fm)
   };
   return { ...detail, refinement: computeRefinementStatus(detail) };
@@ -17043,7 +17307,7 @@ function parseOriginalSnapshot(fm) {
 function readBody(filePath) {
   try {
     const raw = readFile2(filePath);
-    return matter72(raw).content;
+    return matter82(raw).content;
   } catch {
     return "";
   }
@@ -17319,8 +17583,16 @@ ${body}`);
 ${out.join("\n\n")}
 `.replace(/\n{3,}/g, "\n\n");
 }
+function ensureH1(body, title) {
+  const trimmed = body.trim();
+  const firstMeaningful = trimmed.split(/\r?\n/).find((l2) => l2.trim());
+  if (firstMeaningful && /^#\s+/.test(firstMeaningful.trim())) return trimmed;
+  return `# ${title}
+
+${trimmed}`;
+}
 function serialize(data, body) {
-  return matter82.stringify(`
+  return matter92.stringify(`
 ${body.trim()}
 `, data);
 }
@@ -17354,6 +17626,7 @@ function createWorkItem(dir, opts) {
   const id = nextWorkItemId(dir);
   const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
   const today22 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const summary = opts.summary?.trim() || intent;
   const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
   const data = {
     type,
@@ -17365,15 +17638,16 @@ function createWorkItem(dir, opts) {
     source,
     generated_by: "kaddo-admin",
     affected_modules: [],
-    summary: intent
+    summary
   };
   if (opts.originalSnapshot) data.original_snapshot = opts.originalSnapshot;
   const answers = opts.answers ?? {};
   const hasAnswers = Object.values(answers).some((v) => v?.trim());
-  const body = hasAnswers ? captureBody(title, type, answers) : freshBody({
+  const providedBody = opts.body?.trim();
+  const body = providedBody ? ensureH1(providedBody, title) : hasAnswers ? captureBody(title, type, answers) : freshBody({
     title,
     type,
-    summary: intent,
+    summary,
     scopeUnknowns: [],
     affectedModules: [],
     moduleCoverage: [],
@@ -17712,6 +17986,7 @@ function buildImplementationHandoff(dir, workItemId) {
   const affectedModules = match.affectedModules;
   const domains = match.domains;
   const scopeConfidence = match.scopeConfidence;
+  const wiResources = parseWorkItemResources2(match.rawFrontmatter);
   const lines = [
     `Implement Work Item ${wiId} \u2014 "${wiTitle}" \u2014 in project "${projectName}" using Kaddo.`,
     "",
@@ -17801,6 +18076,41 @@ function buildImplementationHandoff(dir, workItemId) {
       "Do not copy all legacy knowledge \u2014 assemble proportionally to scope."
     );
   }
+  if (wiResources.length > 0) {
+    lines.push(
+      "",
+      "--- Relevant Resources ---",
+      "",
+      "This Work Item relates to external project resources. The handoff INFORMS you about them \u2014 it",
+      "never connects to them, runs any interface, or reveals credential values. Respect each boundary."
+    );
+    for (const rel of wiResources) {
+      const res = getResource2(dir, rel.id);
+      if (!res) {
+        lines.push("", `- ${rel.id} (role: ${rel.role}) \u2014 definition not found under knowledge/tech/resources/.`);
+        continue;
+      }
+      lines.push("", `- ${res.id} \u2014 ${res.title} (role: ${rel.role})`);
+      if (res.resourceType || res.provider) {
+        lines.push(`    type: ${res.resourceType ?? "\u2014"}${res.provider ? ` \xB7 provider: ${res.provider}` : ""}`);
+      }
+      if (res.purpose) lines.push(`    purpose: ${res.purpose}`);
+      if (res.environments.length > 0) lines.push(`    environments: ${res.environments.join(", ")}`);
+      if (res.interfaces.length > 0) {
+        const ifaces = res.interfaces.map((i) => i.tool || i.provider ? `${i.type} (${i.tool ?? i.provider})` : i.type);
+        lines.push(`    interfaces: ${ifaces.join(", ")}`);
+      }
+      for (const [env, ops] of Object.entries(res.boundaries)) {
+        lines.push(`    boundary (${env}): ${ops.join(", ")}`);
+      }
+      if (res.authRefs.length > 0) lines.push(`    auth references (names only): ${res.authRefs.join(", ")}`);
+    }
+    lines.push(
+      "",
+      "Treat these as knowledge, not availability: an interface being declared does not mean it is",
+      "installed or connected. Do not execute any interface or migration without explicit human confirmation."
+    );
+  }
   lines.push(
     "",
     "--- Implementation Plan ---",
@@ -17821,6 +18131,7 @@ function buildImplementationHandoff(dir, workItemId) {
     projectName,
     lifecycle,
     affectedModules,
+    resources: wiResources,
     domains,
     scopeConfidence,
     hasUnmaterializedDecisions: unmaterialized,
@@ -18072,7 +18383,7 @@ function detectFormat(raw) {
   if (!trimmed) throw new ImportError("EMPTY_INPUT", "Import content is empty.");
   if (trimmed.startsWith("---")) {
     try {
-      const { data } = matter92(trimmed);
+      const { data } = matter102(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)) {
@@ -18094,7 +18405,7 @@ function parseContent(raw) {
   let bodyText = trimmed;
   if (format === "kaddo-frontmatter" || format === "markdown-frontmatter") {
     try {
-      const parsed = matter92(trimmed);
+      const parsed = matter102(trimmed);
       frontmatterFields = parsed.data ?? {};
       bodyText = parsed.content.trim();
     } catch {
@@ -18151,15 +18462,21 @@ function extractSections(body) {
   flush();
   return sections;
 }
+function deriveShortSummary(parsed) {
+  const paragraph = parsed.body.split(/\n{2,}/).map((p) => p.trim()).find((p) => p && !/^#{1,6}\s/.test(p) && !/^>/.test(p) && p !== parsed.title);
+  const base = paragraph ? paragraph.replace(/\s+/g, " ") : parsed.title;
+  return base.length > 280 ? `${base.slice(0, 277).trimEnd()}\u2026` : base;
+}
 function normalizeImportFields(parsed, opts) {
   const discardedFields = [];
   for (const key of Object.keys(parsed.candidateFields)) {
     if (LIFECYCLE_FIELDS.has(key)) discardedFields.push(key);
   }
   const type = opts.userType ? normalizeType(opts.userType) ?? "feature" : parsed.type ?? "feature";
-  const intent = parsed.body && parsed.body !== parsed.title ? `${parsed.title}
-
-${parsed.body}` : parsed.title;
+  const hasRealBody = !!parsed.body && parsed.body !== parsed.title;
+  const intent = parsed.title;
+  const body = hasRealBody ? parsed.body : void 0;
+  const summary = hasRealBody ? deriveShortSummary(parsed) : parsed.title;
   const source = {
     type: opts.importSource === "chat" ? "chat" : "external",
     imported_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
@@ -18167,14 +18484,14 @@ ${parsed.body}` : parsed.title;
   source.source_format = opts.sourceFormat;
   source.source_hash = opts.sourceHash;
   const snapshot = { title: parsed.title };
-  if (parsed.summary !== parsed.title) snapshot.description = parsed.summary;
+  if (summary !== parsed.title) snapshot.description = summary;
   if (typeof parsed.candidateFields.type === "string") snapshot.type = parsed.candidateFields.type;
   if (typeof parsed.candidateFields.status === "string") snapshot.status = parsed.candidateFields.status;
   if (Array.isArray(parsed.candidateFields.labels)) {
     const labels = parsed.candidateFields.labels.filter((l2) => typeof l2 === "string");
     if (labels.length > 0) snapshot.labels = labels;
   }
-  return { type, intent, source, snapshot, discardedFields };
+  return { type, intent, summary, body, source, snapshot, discardedFields };
 }
 function computeContentHash(raw) {
   return crypto3.createHash("sha256").update(raw.trim(), "utf-8").digest("hex");
@@ -18185,7 +18502,7 @@ function findDuplicateByHash(dir, hash) {
     const raw = readFile2(item.filePath);
     if (!raw) continue;
     try {
-      const { data } = matter92(raw);
+      const { data } = matter102(raw);
       const source = data?.source;
       if (source && typeof source === "object" && !Array.isArray(source)) {
         const s = source;
@@ -18260,6 +18577,8 @@ function importWorkItem(dir, opts) {
   const result = createWorkItem(dir, {
     intent: normalized.intent,
     type: normalized.type,
+    summary: normalized.summary,
+    body: normalized.body,
     source: normalized.source,
     originalSnapshot: normalized.snapshot
   });
@@ -19078,7 +19397,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 matter112.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
+  return matter122.stringify("\n" + (input.body ?? defaultBody(input.title.trim())), data);
 }
 function createInitiative(dir, input) {
   if (!input.title?.trim()) throw new InitiativeWriteError("Initiative title is required.");
@@ -19102,10 +19421,10 @@ function transitionInitiative(dir, id, to) {
     throw new InitiativeWriteError(`Invalid transition ${ini.status} \u2192 ${to}.`);
   }
   const raw = readFile2(ini.filePath);
-  const { data, content } = matter112(raw, {});
+  const { data, content } = matter122(raw, {});
   data.status = to;
   if (to === "completed") data.completed_at = today2();
-  const newContent = matter112.stringify(content, data);
+  const newContent = matter122.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after transition.");
@@ -19115,7 +19434,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 } = matter112(raw, {});
+  const { data, content } = matter122(raw, {});
   const existing = Array.isArray(data.candidates) ? data.candidates : [];
   const fallbackId = `WI-CANDIDATE-${String(existing.length + 1).padStart(3, "0")}`;
   const normalized = normalizeCandidate(candidate, fallbackId);
@@ -19123,7 +19442,7 @@ function addCandidate(dir, id, candidate) {
     throw new InitiativeWriteError(`Candidate ${normalized.id} already exists in ${id}.`);
   }
   data.candidates = [...existing, candidateToData(normalized)];
-  const newContent = matter112.stringify(content, data);
+  const newContent = matter122.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding a candidate.");
@@ -19133,7 +19452,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 } = matter112(raw, {});
+  const { data, content } = matter122(raw, {});
   if (patch.title !== void 0) {
     if (!patch.title.trim()) throw new InitiativeWriteError("Initiative title cannot be empty.");
     data.title = patch.title.trim();
@@ -19143,7 +19462,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 = matter112.stringify(content, data);
+  const newContent = matter122.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after update.");
@@ -19161,10 +19480,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 } = matter112(raw, {});
+  const { data, content } = matter122(raw, {});
   const existing = Array.isArray(data.external_links) ? data.external_links : [];
   data.external_links = [...existing, externalLinkToData(link)];
-  const newContent = matter112.stringify(content, data);
+  const newContent = matter122.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after adding an external link.");
@@ -19233,7 +19552,7 @@ function buildWorkItemContent(wiId, iniId, candidate) {
     "_What did we learn? Update after completion._",
     ""
   ].join("\n");
-  return matter112.stringify("\n" + body, data);
+  return matter122.stringify("\n" + body, data);
 }
 function materializeCandidate(dir, id, candidateId) {
   const ini = getInitiative(dir, id);
@@ -19250,13 +19569,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 } = matter112(raw, {});
+  const { data, content } = matter122(raw, {});
   const cands = Array.isArray(data.candidates) ? data.candidates : [];
   for (const c of cands) {
     if (c && typeof c === "object" && String(c.id) === candidateId) c.materialized_as = wiId;
   }
   data.candidates = cands;
-  const newContent = matter112.stringify(content, data);
+  const newContent = matter122.stringify(content, data);
   writeFile2(ini.filePath, newContent);
   const updated = parseInitiative2(dir, ini.filePath, newContent);
   if (!updated) throw new InitiativeWriteError("Failed to parse the Initiative after materialization.");
@@ -19462,12 +19781,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 = matter12(raw);
+  const parsed = matter13(raw);
   const data = { ...parsed.data };
   const today3 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
   data.ready_at = today3;
-  const newContent = matter12.stringify(parsed.content, data);
+  const newContent = matter13.stringify(parsed.content, data);
   const posixPath = item.path.replace(/\\/g, "/");
   let newRelPath = item.path;
   if (posixPath.includes("/work-items/draft/")) {
@@ -19630,11 +19949,19 @@ function setTelemetryConsentTool(root, args) {
   persistConsent(root, consent);
   return ok({ applied: true, consent, message: `Telemetry ${consent}.` });
 }
+function listResourcesTool(root) {
+  return ok(getResources(root));
+}
+function getResourceTool(root, id) {
+  const resource = getResource(root, id);
+  if (!resource) return fail(`Project Resource "${id}" not found.`);
+  return ok(resource);
+}
 
 // src/multirepo.ts
 import fs5 from "fs";
 import path4 from "path";
-import matter13 from "gray-matter";
+import matter14 from "gray-matter";
 import { parse as parseYaml11, stringify as stringifyYaml7 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
@@ -19786,7 +20113,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 = matter13(raw);
+  const parsed = matter14(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) : [] })) : [];
@@ -19839,7 +20166,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 = matter13(raw);
+  const parsed = matter14(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) : [] })) : [];
@@ -19925,7 +20252,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 = matter13(raw);
+  const parsed = matter14(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) : [] })) : [];
@@ -20685,14 +21012,14 @@ function systemImpactCandidatesTool(root, args) {
 }
 
 // ../cli/src/services/integrations.ts
-import matter15 from "gray-matter";
+import matter16 from "gray-matter";
 import { parse as parseYaml13, stringify as stringifyYaml9 } from "yaml";
 
 // ../cli/src/core/work-item-write.ts
 import fs7 from "fs";
 import path6 from "path";
 import crypto4 from "crypto";
-import matter14 from "gray-matter";
+import matter15 from "gray-matter";
 var SECTION_ORDER2 = [
   "Actor",
   "Outcome",
@@ -21740,7 +22067,7 @@ async function integrationsWorkItemTool(root, args) {
 }
 
 // ../cli/src/core/context-pack.ts
-import matter16 from "gray-matter";
+import matter17 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR4 = "knowledge";
 function readScanJson(dir) {
@@ -21753,7 +22080,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph4(markdown) {
-  const body = matter16(markdown).content.trim();
+  const body = matter17(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -21807,6 +22134,8 @@ function toContextWorkItem(a2) {
   wi.validationStatus = a2.validationStatus || (isHistorical ? "not-assessed" : void 0);
   wi.releaseStatus = a2.releaseStatus || (isHistorical ? "not-assessed" : void 0);
   if (a2.affectedModules.length > 0) wi.affectedModules = a2.affectedModules;
+  const wiResources = parseWorkItemResources(a2.rawFrontmatter);
+  if (wiResources.length > 0) wi.resources = wiResources;
   if (a2.scopeConfidence) wi.scopeConfidence = a2.scopeConfidence;
   if (a2.moduleCoverage) wi.moduleCoverage = a2.moduleCoverage;
   if (a2.impactAnalysis) wi.impactAnalysis = a2.impactAnalysis;
@@ -23139,6 +23468,16 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => markWorkItemReady(root, args.id, args.confirm)))
   );
+  server.registerTool(
+    "kaddo_list_resources",
+    { title: "List Project Resources", description: "List external systems the project uses (databases, cloud, APIs\u2026), read-only, no secrets.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listResourcesTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_resource",
+    { title: "Get Project Resource", description: "Get one Project Resource by ID: purpose, environments, access interfaces, boundaries and auth references (never values).", inputSchema: { id: z4.string() } },
+    async (args) => toolText(guarded(root, () => getResourceTool(root, args.id)))
+  );
   server.registerTool(
     "kaddo_list_capsules",
     { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },

package/package.json

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