@kaddo/cli 3.14.0 → 3.16.0

package/dist/index.js

@@ -600,6 +600,21 @@ ${issues}`);
   }
   return parsed.data;
 }
+function requireConfig(dir) {
+  let config;
+  try {
+    config = loadConfig(dir);
+  } catch (err) {
+    const message = err instanceof ConfigError ? err.message : String(err);
+    console.error(message);
+    process.exit(1);
+  }
+  if (!config) {
+    console.error("No .kaddo/config.yml found. Run `kaddo init` first.");
+    process.exit(1);
+  }
+  return config;
+}
 function nextStepsForState(state) {
   switch (state) {
     case "new":
@@ -624,8 +639,8 @@ function createGuidanceForState(state) {
 }
 function describeProject(config) {
   const state = config.project.state;
-  const stateLabel4 = state === "pre-ai" ? "pre-AI" : state;
-  return `${stateLabel4} ${config.project.structure}`;
+  const stateLabel3 = state === "pre-ai" ? "pre-AI" : state;
+  return `${stateLabel3} ${config.project.structure}`;
 }
 
 // src/core/command-help.ts
@@ -1611,6 +1626,33 @@ var RESPONSIBILITY_MATRIX = {
     ],
     next: ["kaddo scan", "kaddo owners suggest", "kaddo guard", "kaddo explain"]
   },
+  "capsule-agent": {
+    agent: "capsule-agent",
+    responsibleFor: ["Refining/validating a Knowledge Capsule for external sharing"],
+    produces: [".kaddo/exports/<system>.capsule.md"],
+    canSuggest: ["kaddo capsule export"],
+    cannotSuggest: [
+      "exporting secrets",
+      "exporting source code",
+      "inventing contracts",
+      "code",
+      "git"
+    ],
+    next: ["kaddo capsule export"]
+  },
+  "ownership-agent": {
+    agent: "ownership-agent",
+    responsibleFor: ["Precise code: ownership for Work Items and artifacts"],
+    produces: ["proposed code: globs"],
+    canSuggest: ["kaddo owners suggest", "kaddo guard"],
+    cannotSuggest: [
+      "code",
+      "branches",
+      "commits",
+      "modifying files without confirmation"
+    ],
+    next: ["kaddo owners suggest", "kaddo guard"]
+  },
   "guard-agent": {
     agent: "guard-agent",
     responsibleFor: ["Knowledge drift"],
@@ -1884,13 +1926,15 @@ Generated from Kaddo Context Pack.
 
 Save the architecture overview as \`knowledge/tech/current-state.md\`, supporting notes as
 \`knowledge/tech/architecture-notes.md\`, and decision candidates as
-\`knowledge/tech/decision-candidates.md\`.
+\`knowledge/tech/decision-candidates.md\`. Final ADRs always live under
+\`knowledge/tech/decisions/\` \u2014 never directly in \`knowledge/tech/\`.
 
 ## Quality Checklist
 
 - Every component is backed by evidence from the context pack.
 - Assumptions and confidence are explicit.
 - No final decisions are asserted \u2014 only candidates.
+- Final ADRs go to \`knowledge/tech/decisions/\`, not \`knowledge/tech/\`.
 - Open questions are listed.
 `;
 var ROADMAP_AGENT = `# Roadmap Agent
@@ -2209,12 +2253,16 @@ Generated from Kaddo Context Pack.
 
 ## Where to Save the Result
 
-Save the output as \`knowledge/tech/decision-candidates.md\`.
+Save decision **candidates** as \`knowledge/tech/decision-candidates.md\`. When a candidate becomes
+a **final ADR**, it must live under \`knowledge/tech/decisions/\` (one file per decision, e.g.
+\`knowledge/tech/decisions/ADR-0001-<slug>.md\`) \u2014 **never** directly in \`knowledge/tech/\`.
+(Decision = the concept \xB7 ADR = the format \xB7 Path = \`knowledge/tech/decisions/\`.)
 
 ## Quality Checklist
 
 - Each candidate has context and alternatives.
 - No decision is asserted as final.
+- Final ADRs go to \`knowledge/tech/decisions/\`, never to \`knowledge/tech/\` directly.
 - Assumptions are marked.
 - Validation needs are explicit.
 `;
@@ -2913,6 +2961,148 @@ Code, tests and migrations live in the repository. Knowledge updates go under \`
 - Affected knowledge is updated.
 - Commit is suggested and awaits human confirmation \u2014 never run automatically.
 `;
+var CAPSULE_AGENT = `# Capsule Agent
+
+## Role
+
+You are the Kaddo Capsule Agent. Your job is to refine and validate a **Knowledge Capsule** \u2014 a
+minimal, portable summary another project can consume as external context \u2014 before it is exported.
+
+You do not write code, you never invent contracts, and you mark uncertainties. A capsule contains
+**knowledge, not code or secrets**.
+
+## When to Use
+
+Use this agent before sharing a Knowledge Capsule (after \`kaddo capsule export\` produced a draft),
+to sharpen its purpose, capabilities, public contracts, risks, owners and out-of-scope.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` plus \`knowledge/product/capabilities.md\`,
+\`knowledge/tech/current-state.md\`, \`knowledge/tech/decisions/\` and any contracts
+(\`knowledge/tech/contracts/\`) that exist. Also provide the draft capsule from
+\`.kaddo/exports/<system>.capsule.md\`.
+
+## Expected Output
+
+A refined Markdown capsule intended to be saved as \`.kaddo/exports/<system>.capsule.md\`.
+
+## Instructions
+
+1. Summarize what the system does and the boundaries of this capsule.
+2. List the **public contracts** consumers integrate with (APIs, events) \u2014 never invent them.
+3. List exposed capabilities, dependencies and known integration risks.
+4. Identify owners and relevant ADRs.
+5. State what is **out of scope** for this capsule.
+6. Mark any unknowns explicitly.
+
+## Constraints
+
+- Do **not** export secrets, tokens, credentials, private keys, PII or internal sensitive URLs.
+- Do **not** export source code.
+- Do **not** invent contracts or integrations.
+- Summarize and mark boundaries; prefer "unknown" over guessing.
+
+## Output Format
+
+\`\`\`markdown
+---
+type: knowledge-capsule
+system: <system>
+version: 1
+updated_at: <YYYY-MM-DD>
+owner: <team>
+---
+
+# <System> \u2014 Knowledge Capsule
+
+## Purpose
+## Responsibilities
+## Exposed Capabilities
+## Public Contracts
+## Dependencies
+## Known Risks
+## Relevant ADRs
+## Owners
+## Out of Scope
+## Usage Notes
+\`\`\`
+
+## Where to Save the Result
+
+Save as \`.kaddo/exports/<system>.capsule.md\`. The human reviews the security checklist (no
+secrets, no source) before sharing.
+
+## Quality Checklist
+
+- Purpose and boundaries are clear.
+- Public contracts are real (not invented) \u2014 unknowns are marked.
+- Capabilities, dependencies, risks, owners and out-of-scope are present.
+- No secrets, credentials, PII or source code are included.
+`;
+var OWNERSHIP_AGENT = `# Ownership Agent
+
+## Role
+
+You are the Kaddo Ownership Agent. Your job is to propose **precise** \`code:\` ownership globs for
+Work Items and knowledge artifacts, so Guard can relate code changes to the right knowledge.
+
+You do not write code, you do not modify files, and you never run Git. You propose; the human
+confirms and applies (with \`kaddo owners suggest\`).
+
+## When to Use
+
+Use this agent after \`kaddo scan\` and \`kaddo context\`, when Work Items or artifacts are missing
+\`code:\` ownership, or when existing ownership is too broad or inaccurate.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` as the primary input, plus the Work Items under
+\`knowledge/delivery/work-items/\`, \`knowledge/tech/codebase.md\` and \`knowledge/inventory.md\` when
+they exist (for the real source structure).
+
+## Expected Output
+
+For each artifact, a precise set of \`code:\` globs.
+
+## Instructions
+
+1. Map each Work Item / artifact to the smallest set of paths that actually implement it.
+2. Prefer **narrow** globs (e.g. \`src/payments/**\`) over broad ones (e.g. \`src/**\`).
+3. Use real paths from the inventory/codebase \u2014 do not invent directories.
+4. Include relevant root files (e.g. \`package.json\`, \`tsconfig.json\`) when they belong.
+5. Flag artifacts where ownership is genuinely unclear instead of guessing broadly.
+
+## Constraints
+
+- Do not implement code.
+- Do not modify files without confirmation \u2014 propose globs for the human to apply.
+- Do not create branches or commits; never run Git.
+- Prefer precision: broad globs reduce Guard usefulness.
+
+## Output Format
+
+\`\`\`yaml
+# <Work Item id> \u2014 proposed ownership
+code:
+  - package.json
+  - tsconfig.json
+  - src/cli/**
+  - src/shared/**
+\`\`\`
+
+## Where to Save the Result
+
+The human applies the proposed globs to the artifact's front matter with \`kaddo owners suggest\`
+(or by editing the \`code:\` field). This agent does not write files.
+
+## Quality Checklist
+
+- Globs are narrow and based on real paths.
+- No \`src/**\`-style catch-alls unless truly justified.
+- Unclear ownership is flagged, not guessed.
+- Output is a proposal for human confirmation \u2014 nothing is applied automatically.
+`;
 var BACKLOG_AGENT = `# Backlog Agent
 
 ## Role
@@ -3024,7 +3214,11 @@ var AGENT_PROMPTS = [
   // Implementation (the only agent that may suggest a branch — VS-044)
   { fileName: "implementation-agent.md", content: IMPLEMENTATION_AGENT },
   // Backlog capture (idea → draft / roadmap candidate — VS-050)
-  { fileName: "backlog-agent.md", content: BACKLOG_AGENT }
+  { fileName: "backlog-agent.md", content: BACKLOG_AGENT },
+  // Ownership proposals (precise code: globs — VS-052)
+  { fileName: "ownership-agent.md", content: OWNERSHIP_AGENT },
+  // Knowledge Capsule refinement (external context — VS-054)
+  { fileName: "capsule-agent.md", content: CAPSULE_AGENT }
   // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
 ].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
@@ -3039,13 +3233,15 @@ var AGENT_GROUPS = {
     "security-agent.md",
     "standards-agent.md",
     "module-design-agent.md",
-    "adr-agent.md"
+    "adr-agent.md",
+    "capsule-agent.md"
   ],
   delivery: [
     "backlog-agent.md",
     "roadmap-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
+    "ownership-agent.md",
     "git-strategy-agent.md"
   ],
   utilities: ["legacy-agent.md"]
@@ -3079,7 +3275,8 @@ var RECOMMENDED_BY_STATE = {
     "roadmap-agent.md",
     "backlog-agent.md",
     "work-item-agent.md",
-    "implementation-agent.md"
+    "implementation-agent.md",
+    "ownership-agent.md"
   ],
   legacy: [
     "legacy-agent.md",
@@ -3088,7 +3285,8 @@ var RECOMMENDED_BY_STATE = {
     "roadmap-agent.md",
     "backlog-agent.md",
     "work-item-agent.md",
-    "implementation-agent.md"
+    "implementation-agent.md",
+    "ownership-agent.md"
   ]
 };
 function recommendedAgents(state) {
@@ -3757,7 +3955,7 @@ function formatList(items) {
   return items.map((i) => `- ${i.trim()}`).join("\n");
 }
 function buildFrontMatter(id, type, level, title, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const lines = [
     "---",
     `type: ${type}`,
@@ -3769,7 +3967,7 @@ function buildFrontMatter(id, type, level, title, answers) {
     `initiative:`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `summary: "${answers.problem?.split(".")[0] ?? title}"`,
     "---"
   ];
@@ -3839,7 +4037,7 @@ _What did we learn from this change? Update after completion._
   return sections.join("\n");
 }
 function buildModuleFrontMatter(id, modType, title, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const extra = modType.extraFrontMatter ?? {};
   const extraLines = Object.entries(extra).map(
     ([k, v]) => `${k}: ${JSON.stringify(v)}`
@@ -3855,7 +4053,7 @@ function buildModuleFrontMatter(id, modType, title, answers) {
     `initiative:`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `summary: "${title}"`,
     ...extraLines,
     "---"
@@ -3940,8 +4138,8 @@ async function runCreate(type, opts = {}) {
     answers[question.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildFrontMatter(id, workItemType, level, title.trim(), answers);
   const body = buildBody(workItemType, level, title.trim(), answers, levelDef.qualityGate);
@@ -3981,8 +4179,8 @@ async function runCreateModule(dir, modType) {
     answers[q.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildModuleFrontMatter(id, modType, title.trim(), answers);
   const body = buildModuleBody(modType, title.trim(), answers);
@@ -4004,7 +4202,7 @@ function resolveCandidateLevel(candidate, type) {
   return getLevelForType(type);
 }
 function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = (answers.problem?.split(".")[0] ?? candidate.expectedValue ?? title).trim();
   const initiative = candidate.initiative?.title ?? candidate.initiative?.id ?? "";
   const lines = [
@@ -4018,7 +4216,7 @@ function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
     `initiative: "${initiative.replace(/"/g, "'")}"`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `source: roadmap`,
     `source_id: ${candidate.id}`,
     `source_initiative: ${candidate.initiative?.id ?? "unknown"}`,
@@ -4114,8 +4312,8 @@ function buildRoadmapWorkItem(opts) {
   const { id, type, level, candidate } = opts;
   const answers = opts.answers ?? {};
   const title = candidate.title.trim();
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const qualityGate = getLevel(level).qualityGate;
   const frontMatter2 = buildRoadmapFrontMatter(id, type, level, title, candidate, answers);
   const body = buildRoadmapBody(type, level, title, candidate, answers, qualityGate);
@@ -4234,6 +4432,14 @@ async function isGitRepo(dir) {
     return false;
   }
 }
+async function getUntrackedFiles() {
+  try {
+    const result = await execa("git", ["ls-files", "--others", "--exclude-standard"]);
+    return result.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 // src/services/artifact-reader.ts
 import matter from "gray-matter";
@@ -4254,7 +4460,8 @@ function parseArtifact(filePath, raw) {
       status: String(data.status ?? ""),
       phase: String(data.phase ?? ""),
       initiative: String(data.initiative ?? data.source_initiative ?? ""),
-      source: data.source ? String(data.source) : ""
+      source: data.source ? String(data.source) : "",
+      sourceId: String(data.source_id ?? "")
     };
   } catch {
     return null;
@@ -4892,6 +5099,15 @@ async function runGuard(opts = {}) {
   const plugins = resolvePlugins(config.plugins ?? []);
   const mode = opts.staged ? "staged" : "head";
   const currentFiles = await getModifiedFiles(mode);
+  const untrackedFiles = opts.staged ? [] : await getUntrackedFiles();
+  const printUntracked = () => {
+    if (untrackedFiles.length === 0 || jsonMode) return;
+    console.log("");
+    console.log(`Untracked files detected (${untrackedFiles.length}):`);
+    for (const f of untrackedFiles.slice(0, 10)) console.log(`  - ${f}`);
+    if (untrackedFiles.length > 10) console.log(`  \u2026and ${untrackedFiles.length - 10} more`);
+    console.log("Guard may not fully evaluate these files until they are tracked. (FYI \u2014 non-blocking)");
+  };
   let workspaceScan = null;
   if (opts.workspace) {
     workspaceScan = await collectWorkspaceChanges(dir, mode);
@@ -4901,6 +5117,7 @@ async function runGuard(opts = {}) {
   if (touchedFiles.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     console.log("kaddo guard: no modified files detected.");
+    printUntracked();
     return;
   }
   const archDir = join(dir, ARCH_DIR3);
@@ -4940,10 +5157,12 @@ async function runGuard(opts = {}) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     printHeader(touchedFiles);
     console.log("  No artifact ownership matches found.");
+    printUntracked();
     return;
   }
   if (workspaceScan) printWorkspaceHeader(workspaceScan);
   printHeader(touchedFiles);
+  printUntracked();
   for (const match of activeMatches) {
     printFYI(match, dir);
   }
@@ -5017,8 +5236,8 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter2 from "gray-matter";
-import { parse as parseYaml8 } from "yaml";
+import matter3 from "gray-matter";
+import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
 function layer(layers, name) {
@@ -5069,22 +5288,30 @@ function assessPhase(input) {
   const firstOf = (s) => items.find((i) => i.lifecycle === s);
   let recommendedAgents2 = [];
   let nextStep = "";
+  let llmInstructions = [];
   switch (phase) {
     case "Discovery": {
       const m = firstMissingLayerAgent(input.layers);
       recommendedAgents2 = [m.agent];
       nextStep = m.step;
+      llmInstructions = [`Use the ${m.agent} to fill the missing base knowledge.`, "Do not write code."];
       break;
     }
     case "Planning": {
       recommendedAgents2 = ["roadmap-agent"];
       nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
+      llmInstructions = ["Use the roadmap-agent.", "Do not write code.", "Generate roadmap candidates."];
       break;
     }
     case "Delivery Preparation": {
       recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
       const n = input.roadmap.remaining || input.roadmap.candidates;
       nextStep = `Run \`kaddo create --from roadmap\`${n ? ` (${n} candidate(s))` : ""}, then refine with work-item-agent`;
+      llmInstructions = [
+        "Materialize roadmap candidates with `kaddo create --from roadmap`.",
+        "Use the work-item-agent to refine them.",
+        "Do not implement yet."
+      ];
       break;
     }
     case "Active Delivery": {
@@ -5092,21 +5319,41 @@ function assessPhase(input) {
         const wi = firstOf("ready");
         recommendedAgents2 = ["implementation-agent"];
         nextStep = wi ? `Start ${wi.id} \u2014 ${wi.title} (ready \u2192 in-progress)` : "Start a ready Work Item";
+        llmInstructions = [
+          "Use the implementation-agent.",
+          "Suggest a branch name only.",
+          "Do not run git commands."
+        ];
       } else if (bs["in-progress"] > 0) {
         const wi = firstOf("in-progress");
         recommendedAgents2 = ["implementation-agent", "kaddo scan", "kaddo owners suggest", "kaddo guard"];
         nextStep = wi ? `Continue ${wi.id} \u2014 ${wi.title}; then run kaddo scan, owners suggest, guard` : "Continue the in-progress Work Item; then scan, owners suggest, guard";
+        llmInstructions = [
+          "Continue the in-progress Work Item with the implementation-agent.",
+          "After changes, run `kaddo scan`, `kaddo owners suggest` and `kaddo guard`.",
+          "Do not commit, push or merge without explicit human confirmation."
+        ];
       } else if (bs.draft > 0) {
         const wi = firstOf("draft");
         recommendedAgents2 = ["work-item-agent"];
         nextStep = wi ? `Refine ${wi.id} from draft to ready` : "Refine a draft Work Item to ready";
+        llmInstructions = [
+          "Refine draft Work Items to ready.",
+          "Use the work-item-agent.",
+          "Do not implement unless the user explicitly asks."
+        ];
       } else if (bs.blocked > 0) {
         const wi = firstOf("blocked");
         recommendedAgents2 = ["work-item-agent"];
         nextStep = wi ? `Resolve the blocker on ${wi.id} \u2014 ${wi.title}` : "Resolve the blockers on active work";
+        llmInstructions = [
+          "Resolve the blockers with the work-item-agent.",
+          "Do not implement blocked work."
+        ];
       }
       if (input.ownership.workItemsMissingOwnership > 0) {
         recommendedAgents2.push("kaddo owners suggest");
+        llmInstructions.push("Ownership is incomplete \u2014 propose `code:` globs (run `kaddo owners suggest`).");
       }
       break;
     }
@@ -5114,18 +5361,213 @@ function assessPhase(input) {
       if (input.roadmap.remaining > 0) {
         recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
         nextStep = `Materialize ${input.roadmap.remaining} remaining roadmap candidate(s)`;
+        llmInstructions = ["Materialize the remaining roadmap candidates.", "Do not implement yet."];
       } else {
         recommendedAgents2 = ["roadmap-agent"];
         nextStep = "No active work \u2014 use roadmap-agent to plan the next initiative";
+        llmInstructions = ["No active work.", "Use the roadmap-agent to plan the next initiative."];
       }
       break;
     }
   }
-  return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep };
+  return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep, llmInstructions };
 }
 
-// src/core/knowledge-discovery.ts
+// src/core/capsule.ts
+import matter2 from "gray-matter";
+import { parse as parseYaml8, stringify as stringifyYaml3 } from "yaml";
 var KNOWLEDGE = "knowledge";
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+}
+function firstParagraph(md) {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n/, "");
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
+  }
+  return "";
+}
+function readIf(dir, rel) {
+  const p2 = join(dir, rel);
+  return exists(p2) ? readFile(p2) : null;
+}
+function headings(md) {
+  return md.split(/\r?\n/).map((l) => l.match(/^#{2,3}\s+(.+?)\s*$/)).filter((m) => Boolean(m)).map((m) => m[1].trim()).filter((h) => !/^(summary|resumen|overview|risks|owners|out of scope)$/i.test(h));
+}
+function buildCapsule(dir, config) {
+  const ownerMap = loadOwners(dir);
+  const owners = [...new Set(Object.values(ownerMap).flat())];
+  const all = discoverKnowledge(dir);
+  const purposeSrc = readIf(dir, `${KNOWLEDGE}/business/business.md`) ?? readIf(dir, `${KNOWLEDGE}/knowledge.md`) ?? "";
+  const capsMd = readIf(dir, `${KNOWLEDGE}/product/capabilities.md`);
+  const risksMd = readIf(dir, `${KNOWLEDGE}/legacy/risks.md`);
+  const adrs = all.filter((a) => a.filePath.replace(/\\/g, "/").includes("/tech/decisions/") && Boolean(a.type)).map((a) => a.title || a.id).filter(Boolean);
+  return {
+    system: config.project.name,
+    version: 1,
+    updatedAt: today(),
+    owner: owners[0] ?? "unknown",
+    sourceProject: config.project.name,
+    purpose: firstParagraph(purposeSrc),
+    responsibilities: [],
+    capabilities: capsMd ? headings(capsMd) : [],
+    contracts: [],
+    dependencies: [],
+    knownRisks: risksMd ? headings(risksMd) : [],
+    adrs,
+    owners,
+    outOfScope: [],
+    usageNotes: []
+  };
+}
+function section2(title, items, placeholder) {
+  if (items.length === 0) return `## ${title}
+
+_${placeholder}_
+`;
+  return `## ${title}
+
+${items.map((i) => `- ${i}`).join("\n")}
+`;
+}
+function renderCapsuleMarkdown(c) {
+  const fm = [
+    "---",
+    "type: knowledge-capsule",
+    `system: ${c.system}`,
+    `version: ${c.version}`,
+    `updated_at: ${c.updatedAt}`,
+    `owner: ${c.owner}`,
+    `source_project: ${c.sourceProject}`,
+    ...c.sourceCommit ? [`source_commit: ${c.sourceCommit}`] : [],
+    "---"
+  ].join("\n");
+  const parts = [
+    fm,
+    "",
+    `# ${c.system} \u2014 Knowledge Capsule`,
+    "",
+    `## Purpose
+
+${c.purpose || "_To be completed by the capsule-agent._"}
+`,
+    section2("Responsibilities", c.responsibilities, "List what this system is responsible for."),
+    section2("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
+    section2("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
+    section2("Dependencies", c.dependencies, "List systems this one depends on."),
+    section2("Known Risks", c.knownRisks, "List integration risks consumers should know."),
+    section2("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
+    section2("Owners", c.owners, "Who owns this system."),
+    section2("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
+    section2("Usage Notes", c.usageNotes, "How consumers should integrate."),
+    "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.",
+    ""
+  ];
+  return parts.join("\n");
+}
+function serializeCapsuleJson(c) {
+  return JSON.stringify({ type: "knowledge-capsule", ...c }, null, 2) + "\n";
+}
+var EXTERNAL_PATH = ".kaddo/external.yml";
+function loadExternalRegistry(dir) {
+  const p2 = join(dir, EXTERNAL_PATH);
+  if (!exists(p2)) return [];
+  try {
+    const parsed = parseYaml8(readFile(p2));
+    return Array.isArray(parsed?.external) ? parsed.external : [];
+  } catch {
+    return [];
+  }
+}
+function serializeExternalRegistry(entries) {
+  return stringifyYaml3({ external: entries });
+}
+function sectionList(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const m = lines[i].match(/^\s*-\s+(.+?)\s*$/);
+    if (m && !/^_.*_$/.test(m[1])) out.push(m[1].trim());
+  }
+  return out;
+}
+function sectionParagraph(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return "";
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const t = lines[i].trim();
+    if (t && !/^_.*_$/.test(t)) return t;
+  }
+  return "";
+}
+function parseCapsule(id, path5, md) {
+  const { data } = matter2(md);
+  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
+  let ageDays = null;
+  if (updatedAt) {
+    const d = Date.parse(updatedAt);
+    if (!Number.isNaN(d)) ageDays = Math.max(0, Math.floor((Date.now() - d) / 864e5));
+  }
+  return {
+    id,
+    path: path5,
+    system: data.system ? String(data.system) : id,
+    owner: data.owner ? String(data.owner) : void 0,
+    updatedAt,
+    purpose: sectionParagraph(md, "Purpose"),
+    capabilities: sectionList(md, "Exposed Capabilities"),
+    contracts: sectionList(md, "Public Contracts"),
+    knownRisks: sectionList(md, "Known Risks"),
+    ageDays
+  };
+}
+function slugId(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "external";
+}
+function addExternalCapsule(dir, sourceFile) {
+  if (!exists(sourceFile)) throw new Error(`Capsule not found: ${sourceFile}`);
+  const raw = readFile(sourceFile);
+  const { data } = matter2(raw);
+  const isCapsuleType = data.type === "knowledge-capsule";
+  const fallbackName = sourceFile.split(/[\\/]/).pop()?.replace(/\.capsule\.md$/, "") ?? "external";
+  const id = slugId(String(data.system ?? fallbackName));
+  const destRel = join("external", `${id}.capsule.md`).replace(/\\/g, "/");
+  writeFile(join(dir, destRel), raw);
+  const entry = {
+    id,
+    type: "knowledge-capsule",
+    path: destRel,
+    owner: data.owner ? String(data.owner) : void 0,
+    lastImportedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+  };
+  const registry = loadExternalRegistry(dir).filter((e) => e.id !== id);
+  registry.push(entry);
+  writeFile(join(dir, EXTERNAL_PATH), serializeExternalRegistry(registry));
+  return { id, destRel, entry, isCapsuleType };
+}
+function loadExternalCapsules(dir) {
+  const out = [];
+  for (const entry of loadExternalRegistry(dir)) {
+    const full = join(dir, entry.path);
+    if (!exists(full) || !isFile(full)) continue;
+    try {
+      out.push(parseCapsule(entry.id, entry.path, readFile(full)));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/core/knowledge-discovery.ts
+var KNOWLEDGE2 = "knowledge";
 var CONSOLIDATED_TYPE = {
   Business: "business",
   Product: "product",
@@ -5167,10 +5609,10 @@ function layerForType(type) {
 }
 function layerFromPath(filePath) {
   const p2 = filePath.replace(/\\/g, "/");
-  if (p2.includes(`/${KNOWLEDGE}/business/`)) return "Business";
-  if (p2.includes(`/${KNOWLEDGE}/product/`)) return "Product";
-  if (p2.includes(`/${KNOWLEDGE}/tech/`)) return "Tech";
-  if (p2.includes(`/${KNOWLEDGE}/delivery/`)) return "Delivery";
+  if (p2.includes(`/${KNOWLEDGE2}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE2}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE2}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE2}/delivery/`)) return "Delivery";
   return null;
 }
 function basename(p2) {
@@ -5183,7 +5625,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE);
+  const archDir = join(dir, KNOWLEDGE2);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -5205,7 +5647,7 @@ function discoverLayers(dir) {
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE, "tech", "decisions"))) acc.Tech.structured = true;
+  if (existsDirWithMd(join(dir, KNOWLEDGE2, "tech", "decisions"))) acc.Tech.structured = true;
   return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
     layer: layer2,
     status: statusFor(layer2, acc[layer2]),
@@ -5258,6 +5700,30 @@ function renderLayersMarkdown(layers) {
 
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
+function normalizeTitle(t) {
+  return t.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, " ").trim();
+}
+function findDuplicateWorkItems(items) {
+  const groups = [];
+  const seen = /* @__PURE__ */ new Set();
+  const bucket = (key, reason, pred) => {
+    const matched = items.filter(pred);
+    if (matched.length > 1) {
+      const id = `${reason}:${key}:${matched.map((m) => m.id).sort().join(",")}`;
+      if (!seen.has(id)) {
+        seen.add(id);
+        groups.push({ reason, items: matched.map((m) => ({ id: m.id, title: m.title })) });
+      }
+    }
+  };
+  for (const sid of new Set(items.map((i) => i.sourceId).filter(Boolean))) {
+    bucket(sid, `same source candidate (${sid})`, (i) => i.sourceId === sid);
+  }
+  for (const nt of new Set(items.map((i) => normalizeTitle(i.title)).filter(Boolean))) {
+    bucket(nt, "same normalized title", (i) => normalizeTitle(i.title) === nt);
+  }
+  return groups;
+}
 function first(values) {
   if (Array.isArray(values)) {
     const v = values.find((x) => typeof x === "string" && x);
@@ -5376,6 +5842,9 @@ function buildProjectExplanation(dir) {
     workItemsMissingOwnership: items.length - withOwnership
   };
   const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
+  const duplicateWorkItems = findDuplicateWorkItems(
+    workItemArtifacts.map((a) => ({ id: a.id || a.title, title: a.title, sourceId: a.sourceId }))
+  );
   const roadmapPath = join(dir, ARCH_DIR4, "delivery", "roadmap.md");
   const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
   const roadmap = roadmapStats(roadmapMd, items.length);
@@ -5425,6 +5894,8 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
+    duplicateWorkItems,
+    externalCapsules: loadExternalCapsules(dir),
     layers,
     roadmap,
     mappedModules,
@@ -5553,11 +6024,31 @@ function renderExplanationHuman(exp) {
     lines.push("- Mapped modules: 0");
     lines.push("");
   }
+  if (exp.externalCapsules.length > 0) {
+    lines.push(`## External Knowledge Capsules: ${exp.externalCapsules.length}`);
+    for (const cap of exp.externalCapsules) {
+      const owner = cap.owner ? ` \u2014 owner: ${cap.owner}` : "";
+      lines.push(`- ${cap.system}${owner}`);
+      if (cap.ageDays !== null && cap.ageDays >= 90) {
+        lines.push(`  \u26A0 capsule last updated ${cap.ageDays} days ago \u2014 it may be stale.`);
+      }
+    }
+    lines.push("");
+  }
   if (exp.missingKnowledge.length > 0) {
     lines.push("## Missing Knowledge");
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
     lines.push("");
   }
+  if (exp.duplicateWorkItems.length > 0) {
+    lines.push("## Possible Duplicate Work Items");
+    for (const g of exp.duplicateWorkItems) {
+      lines.push(`- ${g.reason}:`);
+      for (const i of g.items) lines.push(`  - ${i.id} \u2014 ${i.title}`);
+    }
+    lines.push("Review before continuing (non-blocking).");
+    lines.push("");
+  }
   const assessment = assessPhase(exp);
   lines.push("## Phase");
   lines.push(`- Phase: ${assessment.phase}`);
@@ -5587,7 +6078,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter2(raw);
+    const { data, content } = matter3(raw);
     return { content, data };
   } catch {
     return null;
@@ -5598,7 +6089,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter2(raw);
+    const { content } = matter3(raw);
     return content.trim();
   } catch {
     return null;
@@ -5608,7 +6099,7 @@ function readConfig(dir) {
   const configPath = join(dir, CONFIG_PATH3);
   if (!exists(configPath)) return {};
   try {
-    return parseYaml8(readFile(configPath));
+    return parseYaml9(readFile(configPath));
   } catch {
     return {};
   }
@@ -5694,8 +6185,8 @@ function explainForAgent(dir, artifacts, opts) {
     since: opts.since ?? null
   };
   if (knowledge) {
-    const firstParagraph2 = knowledge.content.trim().split("\n\n").find((p2) => p2.trim() && !p2.startsWith("#"));
-    output.knowledge_summary = firstParagraph2?.trim() ?? "";
+    const firstParagraph3 = knowledge.content.trim().split("\n\n").find((p2) => p2.trim() && !p2.startsWith("#"));
+    output.knowledge_summary = firstParagraph3?.trim() ?? "";
   }
   const mappedArtifacts = artifacts.filter((a) => a.type !== "current-state" && a.type !== "roadmap").map((a) => ({
     id: a.id,
@@ -5767,7 +6258,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -5779,8 +6270,8 @@ function readScanJson(dir) {
     return null;
   }
 }
-function firstParagraph(markdown) {
-  const body = matter3(markdown).content.trim();
+function firstParagraph2(markdown) {
+  const body = matter4(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -5788,7 +6279,7 @@ function readMarkdownSummary(dir, file) {
   const p2 = join(dir, ARCH_DIR6, file);
   if (!exists(p2)) return null;
   try {
-    return firstParagraph(readFile(p2));
+    return firstParagraph2(readFile(p2));
   } catch {
     return null;
   }
@@ -5950,12 +6441,15 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase,
     deliveryMix,
+    external: loadExternalCapsules(dir),
     mappedModules,
     missing,
+    // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
+    // contradicts the Current Phase block above it.
     handoff: {
-      recommendedAgents: recommendedAgentsForState(state),
-      nextSteps: nextStepsForState2(state),
-      instructions: LLM_INSTRUCTIONS,
+      recommendedAgents: phase.recommendedAgents.length > 0 ? phase.recommendedAgents : recommendedAgentsForState(state),
+      nextSteps: phase.nextStep ? [phase.nextStep] : nextStepsForState2(state),
+      instructions: phase.llmInstructions.length > 0 ? phase.llmInstructions : LLM_INSTRUCTIONS,
       operatingRules: OPERATING_RULES
     }
   };
@@ -5965,9 +6459,6 @@ function serializeContextPackJson(pack) {
 }
 
 // src/templates/context-pack-template.ts
-function stateLabel2(state) {
-  return state === "pre-ai" ? "pre-AI" : state;
-}
 function renderContextPack(pack) {
   const { project, scan: scan2, knowledge, missing, handoff } = pack;
   const parts = [];
@@ -6101,6 +6592,21 @@ function renderContextPack(pack) {
       "Note: Kaddo does not scan secondary repositories during `context`. Mapped modules come from `.kaddo/modules.yml` and module artifacts only.\n"
     );
   }
+  if (pack.external.length > 0) {
+    parts.push("## External Knowledge\n");
+    parts.push(
+      "Imported Knowledge Capsules \u2014 minimal context about external systems (not their source).\n"
+    );
+    for (const cap of pack.external) {
+      const lines = [`### ${cap.system}`, ""];
+      if (cap.purpose) lines.push(`- Purpose: ${cap.purpose}`);
+      if (cap.capabilities.length) lines.push(`- Capabilities: ${cap.capabilities.join(", ")}`);
+      if (cap.contracts.length) lines.push(`- Contracts: ${cap.contracts.join(", ")}`);
+      if (cap.owner) lines.push(`- Owner: ${cap.owner}`);
+      if (cap.knownRisks.length) lines.push(`- Known risks: ${cap.knownRisks.join("; ")}`);
+      parts.push(lines.join("\n") + "\n");
+    }
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -6108,11 +6614,11 @@ function renderContextPack(pack) {
     parts.push("_None \u2014 all expected context is present._\n");
   }
   parts.push("## Recommended Agent Handoff\n");
-  parts.push(`Recommended agents for a ${stateLabel2(project.state)} project:
+  parts.push(`Recommended next for the **${pack.phase.phase}** phase:
 `);
   parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
   if (handoff.nextSteps.length > 0) {
-    parts.push("Next steps:\n");
+    parts.push("Next step:\n");
     parts.push(handoff.nextSteps.map((s) => `- ${s}`).join("\n") + "\n");
   }
   parts.push("## Instructions for the LLM\n");
@@ -6211,7 +6717,7 @@ function buildUnderstandPlan(dir, config) {
 }
 
 // src/templates/understand-template.ts
-function stateLabel3(state) {
+function stateLabel2(state) {
   return state === "pre-ai" ? "pre-AI" : state;
 }
 function agentName(file) {
@@ -6234,7 +6740,7 @@ function renderUnderstand(plan) {
     ].join("\n") + "\n"
   );
   parts.push("## Recommended Agent Flow\n");
-  parts.push(`Recommended order for a ${stateLabel3(project.state)} project:
+  parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
 `);
   parts.push(
     steps.map((s, i) => {
@@ -6316,7 +6822,7 @@ function renderUnderstandTerminal(plan) {
 }
 
 // src/core/delivery.ts
-import { parse as parseYaml9 } from "yaml";
+import { parse as parseYaml10 } from "yaml";
 function slugify2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -6422,6 +6928,14 @@ function runUnderstand() {
   if (assessment.nextStep) {
     console.log(`Next step: ${assessment.nextStep}`);
   }
+  if (exp.externalCapsules.length > 0) {
+    console.log("");
+    console.log("External knowledge:");
+    for (const cap of exp.externalCapsules) {
+      console.log(`  - ${cap.system}${cap.owner ? ` (owner: ${cap.owner})` : ""}`);
+    }
+    console.log("  \u2192 Review the relevant capsule before changing integration behavior with it.");
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");
@@ -6655,14 +7169,14 @@ async function runClassify(opts = {}) {
 }
 
 // src/commands/status.ts
-import { parse as parseYaml10 } from "yaml";
+import { parse as parseYaml11 } from "yaml";
 var ARCH_DIR8 = "knowledge";
 var CONFIG_PATH4 = ".kaddo/config.yml";
 function loadConfig3(dir) {
   const p2 = join(dir, CONFIG_PATH4);
   if (!exists(p2)) return {};
   try {
-    return parseYaml10(readFile(p2));
+    return parseYaml11(readFile(p2));
   } catch {
     return {};
   }
@@ -6719,7 +7233,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -6731,7 +7245,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter4(raw);
+  const { data, content } = matter5(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -6756,7 +7270,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter4.stringify(updatedContent, data);
+  const newRaw = matter5.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -6864,13 +7378,13 @@ function runHistory(opts = {}) {
 }
 
 // src/commands/add.ts
-import { parse as parseYaml11, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml12, stringify as stringifyYaml4 } from "yaml";
 var CONFIG_PATH5 = ".kaddo/config.yml";
 function readProjectState(dir) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return void 0;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(readFile(configPath));
     return config.project?.state;
   } catch {
     return void 0;
@@ -6888,12 +7402,12 @@ function markModuleInstalled(dir, configKey, moduleName) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(readFile(configPath));
     config[configKey] = { installed: true, installed_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0] };
     const modules = config.modules ?? [];
     if (!modules.includes(moduleName)) modules.push(moduleName);
     config.modules = modules;
-    writeFile(configPath, stringifyYaml3(config));
+    writeFile(configPath, stringifyYaml4(config));
   } catch {
   }
 }
@@ -6901,7 +7415,7 @@ function isModuleInstalled(dir, configKey) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return false;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(readFile(configPath));
     const moduleConfig = config[configKey];
     return moduleConfig?.installed === true;
   } catch {
@@ -6984,8 +7498,66 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
+function normalizeGlob(input) {
+  let g = input.trim().replace(/\\/g, "/");
+  if (!g) return g;
+  if (g.endsWith("/")) return `${g.slice(0, -1)}/**`;
+  if (!g.includes("*")) {
+    const base = g.split("/").pop() ?? "";
+    const looksLikeFile = /\.[A-Za-z0-9]+$/.test(base);
+    if (!looksLikeFile) return `${g}/**`;
+  }
+  return g;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+    }
+  }
+  return d[m][n];
+}
+function analyzeGlob(dir, input) {
+  const normalized = normalizeGlob(input);
+  const warnings = [];
+  let suggestion;
+  if (/^\*+$/.test(normalized) || /^[^/*]+\/\*\*$/.test(normalized)) {
+    warnings.push(
+      "This glob is broad and may reduce Guard usefulness. Prefer narrower ownership when possible."
+    );
+  }
+  const starIdx = normalized.indexOf("*");
+  const literal = (starIdx >= 0 ? normalized.slice(0, starIdx) : normalized).replace(/\/+$/, "");
+  if (literal && !exists(join(dir, literal))) {
+    const slash = literal.lastIndexOf("/");
+    const parent = slash >= 0 ? literal.slice(0, slash) : "";
+    const target = slash >= 0 ? literal.slice(slash + 1) : literal;
+    const parentFull = parent ? join(dir, parent) : dir;
+    let near;
+    try {
+      if (exists(parentFull)) {
+        near = readDir(parentFull).find(
+          (e) => e !== target && levenshtein(e.toLowerCase(), target.toLowerCase()) <= 2
+        );
+      }
+    } catch {
+    }
+    if (near) {
+      suggestion = `${parent ? parent + "/" : ""}${near}${normalized.slice(literal.length)}`;
+      warnings.push(`Path does not exist. Did you mean ${suggestion}?`);
+    } else {
+      warnings.push(`Path "${literal}" does not exist in the project.`);
+    }
+  }
+  return { normalized, warnings, suggestion };
+}
 function toStringArray3(value) {
   return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
 }
@@ -7048,11 +7620,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter5(raw);
+  const parsed = matter6(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter5.stringify(parsed.content, data);
+  return matter6.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -7131,7 +7703,19 @@ async function chooseGlobs(suggested) {
       placeholder: "src/payments/**",
       validate: (v) => v.trim().length === 0 ? "A glob is required." : void 0
     });
-    chosen.push(glob.trim());
+    const analysis = analyzeGlob(cwd(), glob);
+    for (const w of analysis.warnings) log2.warn(w);
+    let value = analysis.normalized;
+    if (analysis.suggestion) {
+      const useSuggested = await confirm2({
+        message: `Use ${analysis.suggestion} instead?`,
+        initialValue: true
+      });
+      if (useSuggested) value = analysis.suggestion;
+    } else if (analysis.normalized !== glob.trim()) {
+      log2.info(`Normalized to ${analysis.normalized}`);
+    }
+    chosen.push(value);
     addMore = await confirm2({ message: "Add another glob?", initialValue: false });
   }
   return [...new Set(chosen)];
@@ -7214,19 +7798,19 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 }
 
 // src/commands/module-descriptor.ts
-import { parse as parseYaml12, stringify as stringifyYaml4 } from "yaml";
+import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
 var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH2);
   if (!exists(path5)) return null;
   try {
-    return parseYaml12(readFile(path5));
+    return parseYaml13(readFile(path5));
   } catch {
     return null;
   }
 }
 function writeDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml4(descriptor));
+  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml5(descriptor));
 }
 async function runModuleDescriptor(opts) {
   const dir = cwd();
@@ -7321,7 +7905,7 @@ function printDescriptor(d) {
 }
 
 // src/commands/modules-map.ts
-import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
+import { parse as parseYaml14, stringify as stringifyYaml6 } from "yaml";
 
 // src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -7464,7 +8048,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE2 = `---
+var KNOWLEDGE3 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -8474,7 +9058,7 @@ var KADDO_TEMPLATES = [
     description: "What is true about the product right now.",
     whenToUse: "Created by `kaddo init`; keep it current as the product evolves.",
     relatedCommand: "kaddo init",
-    content: KNOWLEDGE2
+    content: KNOWLEDGE3
   },
   // business / product (bootstrap — consolidated, minimal)
   {
@@ -8828,14 +9412,14 @@ function readModulesDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH3);
   if (!exists(path5)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml13(readFile(path5));
+    const parsed = parseYaml14(readFile(path5));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
   }
 }
 function writeModulesDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml5(descriptor));
+  writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml6(descriptor));
 }
 function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
@@ -9125,6 +9709,49 @@ async function runBootstrap(dir = cwd()) {
   );
 }
 
+// src/commands/capsule.ts
+function slug(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+function runCapsuleExport() {
+  const dir = cwd();
+  const config = requireConfig(dir);
+  intro2("kaddo capsule export");
+  const capsule = buildCapsule(dir, config);
+  const name = slug(config.project.name);
+  const mdPath = join(".kaddo", "exports", `${name}.capsule.md`);
+  const jsonPath = join(".kaddo", "exports", `${name}.capsule.json`);
+  writeFile(join(dir, mdPath), renderCapsuleMarkdown(capsule));
+  writeFile(join(dir, jsonPath), serializeCapsuleJson(capsule));
+  log2.success(`Wrote ${mdPath}`);
+  log2.success(`Wrote ${jsonPath}`);
+  log2.info("Refine it with the capsule-agent before sharing \u2014 and never include secrets or source code.");
+  outro2("Knowledge Capsule exported.");
+}
+function runCapsuleAdd(srcPath) {
+  const dir = cwd();
+  requireConfig(dir);
+  intro2("kaddo capsule add");
+  if (!srcPath) {
+    console.error("Usage: kaddo capsule add <path-to-capsule.md>");
+    process.exit(1);
+  }
+  const abs = join(dir, srcPath);
+  const source = exists(abs) ? abs : srcPath;
+  if (!exists(source)) {
+    console.error(`Capsule not found: ${srcPath}`);
+    process.exit(1);
+  }
+  const result = addExternalCapsule(dir, source);
+  if (!result.isCapsuleType) {
+    log2.warn("This file is not marked as a knowledge-capsule (front matter `type: knowledge-capsule`).");
+  }
+  log2.success(`Imported capsule "${result.id}" \u2192 ${result.destRel}`);
+  log2.success("Registered in .kaddo/external.yml");
+  log2.info('Run `kaddo context` \u2014 the pack now includes an "External Knowledge" section.');
+  outro2("External capsule registered.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -9142,6 +9769,13 @@ program.command("bootstrap").description("Build the initial knowledge base for a
 program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike, chore). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
   await runCreate(type ?? "", opts);
 });
+var capsuleCmd = program.command("capsule").description("Export this project as a Knowledge Capsule, or import an external one as context");
+capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").action(() => {
+  runCapsuleExport();
+});
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path5) => {
+  runCapsuleAdd(path5);
+});
 program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").action(async (opts) => {
   await runGuard(opts);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {