@kaddo/cli 3.81.0 → 3.82.0

package/dist/index.js

@@ -4,9 +4,6 @@
 import { createRequire } from "module";
 import { Command } from "commander";
 
-// src/commands/init.ts
-import path2 from "path";
-
 // src/utils/fs.ts
 import fs from "fs";
 import path from "path";
@@ -40,6 +37,9 @@ function join(...parts) {
   return path.join(...parts);
 }
 
+// src/commands/init.ts
+import path2 from "path";
+
 // src/utils/ui.ts
 import * as p from "@clack/prompts";
 var intro2 = (title) => p.intro(title);
@@ -1361,8 +1361,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path10 = i.path.join(".");
-      return path10 ? `  - ${path10}: ${i.message}` : `  - ${i.message}`;
+      const path11 = i.path.join(".");
+      return path11 ? `  - ${path11}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -6732,10 +6732,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path10 = join(dir, IGNORE_FILE);
-  if (!exists(path10)) return [];
+  const path11 = join(dir, IGNORE_FILE);
+  if (!exists(path11)) return [];
   try {
-    const raw = readFile(path10);
+    const raw = readFile(path11);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6743,7 +6743,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path10 = join(dir, IGNORE_FILE);
+  const path11 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -6751,17 +6751,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path10, stringifyYaml2(existing));
+  writeFile(path11, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path10 = join(dir, IGNORE_FILE);
+  const path11 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path10, stringifyYaml2(filtered));
+  writeFile(path11, stringifyYaml2(filtered));
   return true;
 }
 
@@ -6783,11 +6783,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path10 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path10)) return [];
+  const path11 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path11)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path10));
+    parsed = parseYaml5(readFile(path11));
   } catch {
     return [];
   }
@@ -7531,7 +7531,7 @@ function buildGuardHistory(dir) {
     const d = hotspotDir(t.code_path);
     hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path10, warnings]) => ({ path: path10, warnings })).sort((a, b) => b.warnings - a.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path11, warnings]) => ({ path: path11, warnings })).sort((a, b) => b.warnings - a.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -10102,10 +10102,10 @@ function slugify2(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path10 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path10)) return { version: 1, modules: [] };
+  const path11 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path11)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml9(readFile(path10));
+    const parsed = parseYaml9(readFile(path11));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
@@ -10485,7 +10485,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path10, md) {
+function parseCapsule(id, path11, md) {
   const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -10495,7 +10495,7 @@ function parseCapsule(id, path10, md) {
   }
   return {
     id,
-    path: path10,
+    path: path11,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -10525,9 +10525,9 @@ function addExternalCapsule(dir, sourceFile) {
     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));
+  const registry2 = loadExternalRegistry(dir).filter((e) => e.id !== id);
+  registry2.push(entry);
+  writeFile(join(dir, EXTERNAL_PATH), serializeExternalRegistry(registry2));
   return { id, destRel, entry, isCapsuleType };
 }
 function loadExternalCapsules(dir) {
@@ -10581,9 +10581,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path10 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path10) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path10 });
+    const path11 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path11) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path11 });
       presentLayers.push(layer2.id);
     }
   }
@@ -12119,10 +12119,10 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path10 = agentInstallPath(file);
-    const installed = isFile(join(dir, path10));
+    const path11 = agentInstallPath(file);
+    const installed = isFile(join(dir, path11));
     const group = agentGroupOf(file);
-    return { agentPath: path10, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path11, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -12727,6 +12727,7 @@ function parseWorkItemSource(frontmatter) {
       title: optStr(obj.title) ?? optStr(frontmatter.source_title),
       context: optStr(obj.context) ?? optStr(frontmatter.source_context),
       provider: optStr(obj.provider) ?? optStr(frontmatter.source_provider),
+      integration: optStr(obj.integration) ?? optStr(frontmatter.source_integration),
       url: optStr(obj.url) ?? optStr(frontmatter.source_url),
       imported_at: optStr(obj.imported_at) ?? optStr(frontmatter.source_imported_at),
       synced_at: optStr(obj.synced_at) ?? optStr(frontmatter.source_synced_at),
@@ -17378,8 +17379,772 @@ async function runTopologyApply(file, opts = {}) {
   }
 }
 
-// src/core/impact-report.ts
+// src/services/integrations.ts
+import matter11 from "gray-matter";
+import { parse as parseYaml17 } from "yaml";
+
+// src/core/work-item-write.ts
+import fs4 from "fs";
+import path8 from "path";
+import crypto2 from "crypto";
 import matter10 from "gray-matter";
+var WORK_ITEMS_DIR3 = "knowledge/delivery/work-items";
+var WorkItemWriteError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "WorkItemWriteError";
+  }
+  code;
+};
+function revisionOf(raw) {
+  return crypto2.createHash("sha256").update(raw, "utf-8").digest("hex");
+}
+function slugify5(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
+}
+function nextWorkItemId2(dir) {
+  const wiDir = join(dir, WORK_ITEMS_DIR3);
+  let max = 0;
+  const walk = (d) => {
+    if (!exists(d)) return;
+    for (const entry of fs4.readdirSync(d)) {
+      const full = join(d, entry);
+      if (isFile(full)) {
+        const m = entry.match(/WI-(\d+)/);
+        if (m) max = Math.max(max, parseInt(m[1], 10));
+      } else if (!entry.startsWith(".")) {
+        walk(full);
+      }
+    }
+  };
+  walk(wiDir);
+  return `WI-${String(max + 1).padStart(3, "0")}`;
+}
+function atomicWrite2(filePath, content) {
+  fs4.mkdirSync(path8.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs4.writeFileSync(tmp, content, "utf-8");
+  try {
+    fs4.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs4.rmSync(tmp, { force: true });
+    } catch {
+    }
+    throw err;
+  }
+}
+var SECTION_ORDER = [
+  "Actor",
+  "Outcome",
+  "Current behavior",
+  "Target behavior",
+  "Entry points",
+  "End-to-end flow",
+  "Scope unknowns",
+  "Acceptance criteria"
+];
+var KNOWN_HEADINGS = new Set(SECTION_ORDER.map((s) => s.toLowerCase()));
+function renderList(items) {
+  return items.map((i) => `- ${i.trim()}`).filter((l) => l.trim() !== "-").join("\n");
+}
+function renderCriteria(items) {
+  return items.filter((c) => c.text.trim()).map((c) => c.checked === true ? `- [x] ${c.text.trim()}` : c.checked === false ? `- [ ] ${c.text.trim()}` : `- ${c.text.trim()}`).join("\n");
+}
+function desiredSections(input) {
+  const d = /* @__PURE__ */ new Map();
+  const put = (heading, value) => d.set(heading.toLowerCase(), value.trim() ? value.trim() : null);
+  put("Actor", input.actor ?? "");
+  put("Outcome", input.outcome ?? "");
+  put("Current behavior", input.currentBehavior ?? "");
+  put("Target behavior", input.targetBehavior ?? "");
+  put("Entry points", input.entryPoints ?? "");
+  put("End-to-end flow", input.endToEndFlow ?? "");
+  d.set("scope unknowns", input.scopeUnknowns.some((u) => u.trim()) ? renderList(input.scopeUnknowns) : null);
+  d.set("acceptance criteria", input.acceptanceCriteria.some((c) => c.text.trim()) ? renderCriteria(input.acceptanceCriteria) : null);
+  return d;
+}
+function freshBody(input) {
+  const preamble = `# ${input.title}
+
+> Type: ${input.type}`;
+  const out = [];
+  const desired = desiredSections(input);
+  for (const heading of SECTION_ORDER) {
+    const body = desired.get(heading.toLowerCase());
+    if (body != null) out.push(`## ${heading}
+
+${body}`);
+  }
+  return `${preamble}
+
+${out.join("\n\n")}
+`.replace(/\n{3,}/g, "\n\n");
+}
+function serialize(data, body) {
+  return matter10.stringify(`
+${body.trim()}
+`, data);
+}
+var CAPTURE_SECTIONS = [
+  { field: "problem", heading: "Problem" },
+  { field: "expected_result", heading: "Expected result" },
+  { field: "impact", heading: "Impact" },
+  { field: "acceptance_criteria", heading: "Acceptance criteria", list: true },
+  { field: "design", heading: "Design" },
+  { field: "risks", heading: "Risks" }
+];
+function captureBody(title, type, answers) {
+  const out = [`# ${title}`, "", `> Type: ${type}`];
+  for (const { field, heading, list: list2 } of CAPTURE_SECTIONS) {
+    const value = answers[field]?.trim();
+    if (!value) continue;
+    if (list2) {
+      const items = value.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l) => /^[-*+]\s/.test(l) ? l : `- ${l}`);
+      out.push("", `## ${heading}`, "", items.join("\n"));
+    } else {
+      out.push("", `## ${heading}`, "", value);
+    }
+  }
+  return out.join("\n") + "\n";
+}
+function createWorkItem(dir, opts) {
+  const intent = opts.intent.trim();
+  if (!intent) throw new WorkItemWriteError("INVALID_INPUT", "An intent or summary is required.");
+  const type = normalizeType(opts.type.trim()) ?? "";
+  if (!type) throw new WorkItemWriteError("INVALID_INPUT", `Unknown Work Item type "${opts.type}".`);
+  const id = nextWorkItemId2(dir);
+  const title = intent.split(/\r?\n/)[0].trim().slice(0, 120);
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const source = opts.source ? { ...opts.source, inferred: false } : { type: "manual", inferred: false };
+  const data = {
+    type,
+    id,
+    title,
+    status: "draft",
+    work_type: type,
+    created_at: today2,
+    source,
+    generated_by: "kaddo-admin",
+    affected_modules: [],
+    summary: intent
+  };
+  const answers = opts.answers ?? {};
+  const hasAnswers = Object.values(answers).some((v) => v?.trim());
+  const body = hasAnswers ? captureBody(title, type, answers) : freshBody({
+    title,
+    type,
+    summary: intent,
+    scopeUnknowns: [],
+    affectedModules: [],
+    moduleCoverage: [],
+    impactAnalysis: [],
+    acceptanceCriteria: [],
+    decisions: [],
+    relatedKnowledge: [],
+    scopeConfidence: null
+  });
+  const relPath = `${WORK_ITEMS_DIR3}/draft/${id}-${slugify5(title)}.md`;
+  const filePath = join(dir, relPath);
+  if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
+  const raw = serialize(data, body);
+  atomicWrite2(filePath, raw);
+  return { id, path: relPath, revision: revisionOf(raw) };
+}
+
+// ../integrations/src/errors.ts
+var RETRYABLE = /* @__PURE__ */ new Set([
+  "INTEGRATION_RATE_LIMITED",
+  "INTEGRATION_UNAVAILABLE",
+  "INTEGRATION_TIMEOUT"
+]);
+var IntegrationError = class extends Error {
+  code;
+  /** True for transient conditions (rate limit / unavailable / timeout). */
+  retryable;
+  /** A safe, provider-agnostic reason. Never the raw SDK message. */
+  safeMessage;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationError";
+    this.code = code;
+    this.retryable = RETRYABLE.has(code);
+    this.safeMessage = message;
+  }
+};
+function defaultMessageFor(code) {
+  switch (code) {
+    case "INTEGRATION_CONFIG_INVALID":
+      return "The integration configuration is invalid.";
+    case "INTEGRATION_UNAUTHORIZED":
+      return "Authentication failed. Check the configured credentials.";
+    case "INTEGRATION_FORBIDDEN":
+      return "The configured credentials lack permission for this operation.";
+    case "INTEGRATION_NOT_FOUND":
+      return "The requested external resource was not found.";
+    case "INTEGRATION_RATE_LIMITED":
+      return "The external provider is rate limiting requests. Try again later.";
+    case "INTEGRATION_UNAVAILABLE":
+      return "The external provider is temporarily unavailable.";
+    case "INTEGRATION_TIMEOUT":
+      return "The external provider did not respond in time.";
+    case "INTEGRATION_PROVIDER_ERROR":
+      return "The external provider returned an error.";
+    case "UNSUPPORTED_CAPABILITY":
+      return "This adapter does not support the requested capability.";
+  }
+}
+function integrationError(code, message) {
+  return new IntegrationError(code, message ?? defaultMessageFor(code));
+}
+
+// ../integrations/src/identity.ts
+function externalIdentityKey(integrationId, externalId) {
+  return `${integrationId}#${externalId}`;
+}
+function externalDisplayKey(provider, externalId) {
+  return `${provider}#${externalId}`;
+}
+
+// ../integrations/src/config.ts
+var ENV_SUFFIX = "_env";
+var SECRET_KEY = /(token|secret|password|key|pat|apikey|api_key)/i;
+function parseCredentials(raw, id, findings) {
+  const creds = {};
+  if (raw == null) return creds;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    findings.push({ level: "blocking", id, message: `Integration "${id}": credentials must be a mapping of secret references.` });
+    return creds;
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.endsWith(ENV_SUFFIX)) {
+      const name = key.slice(0, -ENV_SUFFIX.length);
+      if (typeof value === "string" && value.trim()) creds[name] = { env: value.trim() };
+      else findings.push({ level: "blocking", id, message: `Integration "${id}": credential "${key}" must name an environment variable.` });
+      continue;
+    }
+    if (SECRET_KEY.test(key) && typeof value === "string") {
+      findings.push({ level: "blocking", id, message: `Integration "${id}": secret "${key}" must not be stored in config. Use "${key}${ENV_SUFFIX}: <ENV_VAR_NAME>".` });
+      continue;
+    }
+    if (value && typeof value === "object" && typeof value.env === "string") {
+      creds[key] = { env: String(value.env) };
+      continue;
+    }
+    findings.push({ level: "warning", id, message: `Integration "${id}": ignoring unrecognized credential entry "${key}".` });
+  }
+  return creds;
+}
+function parseIntegrationsConfig(raw, opts) {
+  const findings = [];
+  const integrations = [];
+  const list2 = raw && typeof raw === "object" && Array.isArray(raw.integrations) ? raw.integrations : Array.isArray(raw) ? raw : [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list2) {
+    if (!entry || typeof entry !== "object") {
+      findings.push({ level: "blocking", message: "Each integration must be a mapping." });
+      continue;
+    }
+    const o = entry;
+    const id = typeof o.id === "string" ? o.id.trim() : "";
+    const adapter = typeof o.adapter === "string" ? o.adapter.trim() : "";
+    if (!id) {
+      findings.push({ level: "blocking", message: 'An integration is missing a required "id".' });
+      continue;
+    }
+    if (seen.has(id)) {
+      findings.push({ level: "blocking", id, message: `Duplicate integration id "${id}".` });
+      continue;
+    }
+    seen.add(id);
+    if (!adapter) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" is missing a required "adapter".` });
+      continue;
+    }
+    if (!opts.adapterIds.has(adapter)) {
+      findings.push({ level: "blocking", id, message: `Integration "${id}" references unknown adapter "${adapter}".` });
+    }
+    const enabled = o.enabled === void 0 ? true : o.enabled === true || o.enabled === "true";
+    const config = o.config && typeof o.config === "object" && !Array.isArray(o.config) ? o.config : {};
+    const credentials = parseCredentials(o.credentials, id, findings);
+    const timeoutMs = typeof o.timeout_ms === "number" ? o.timeout_ms : typeof o.timeoutMs === "number" ? o.timeoutMs : void 0;
+    integrations.push({ id, adapter, enabled, config, credentials, timeoutMs });
+  }
+  return { integrations, findings };
+}
+function resolveCredentials(integration, env) {
+  const credentials = {};
+  const missing = [];
+  for (const [name, ref] of Object.entries(integration.credentials)) {
+    const value = env[ref.env];
+    if (value && value.length > 0) credentials[name] = value;
+    else missing.push(ref.env);
+  }
+  return { credentials, missing };
+}
+
+// ../integrations/src/preview.ts
+function buildImportPreview(item, opts) {
+  return {
+    source: {
+      provider: item.provider,
+      integration: opts.integrationId,
+      externalId: item.externalId,
+      url: item.url,
+      identityKey: externalIdentityKey(opts.integrationId, item.externalId),
+      displayKey: externalDisplayKey(item.provider, item.externalId)
+    },
+    capturedIntent: item.title,
+    description: item.description,
+    externalType: item.type,
+    externalStatus: item.status,
+    kaddoStatus: "draft",
+    kaddoType: opts.type ? opts.type : null,
+    writes: false
+  };
+}
+
+// ../integrations/src/registry.ts
+var DuplicateAdapterError = class extends Error {
+  constructor(id) {
+    super(`An integration adapter with id "${id}" is already registered.`);
+    this.name = "DuplicateAdapterError";
+  }
+};
+var IntegrationRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    if (this.adapters.has(adapter.id)) throw new DuplicateAdapterError(adapter.id);
+    this.adapters.set(adapter.id, adapter);
+  }
+  get(id) {
+    return this.adapters.get(id);
+  }
+  has(id) {
+    return this.adapters.has(id);
+  }
+  list() {
+    return [...this.adapters.values()].sort((a, b) => a.id.localeCompare(b.id));
+  }
+  ids() {
+    return new Set(this.adapters.keys());
+  }
+};
+
+// ../integrations/src/mock-adapter.ts
+var MOCK_ADAPTER_ID = "mock";
+var DEFAULT_ITEMS = [
+  {
+    externalId: "EXT-001",
+    provider: MOCK_ADAPTER_ID,
+    title: "Open public registration to everyone",
+    description: "Open self-service registration to the public once the private beta ends.",
+    type: "Feature",
+    status: "Open",
+    url: "https://example.test/mock/EXT-001",
+    labels: ["registration", "beta"],
+    createdAt: "2026-01-05T10:00:00.000Z",
+    updatedAt: "2026-02-01T09:30:00.000Z",
+    rawMetadata: { board: "delivery" }
+  },
+  {
+    externalId: "EXT-002",
+    provider: MOCK_ADAPTER_ID,
+    title: "Personalize onboarding steps",
+    description: "The onboarding checklist should adapt to what the user has already completed.",
+    type: "Task",
+    status: "To Do",
+    url: "https://example.test/mock/EXT-002",
+    labels: ["onboarding"],
+    createdAt: "2026-01-08T12:00:00.000Z",
+    updatedAt: "2026-01-20T15:00:00.000Z"
+  }
+];
+function simulationOf(context, fallback) {
+  const fromConfig = context.config?.simulate;
+  return typeof fromConfig === "string" ? fromConfig : fallback;
+}
+function readFailure(sim) {
+  switch (sim) {
+    case "unauthorized":
+      throw integrationError("INTEGRATION_UNAUTHORIZED");
+    case "rate-limited":
+      throw integrationError("INTEGRATION_RATE_LIMITED");
+    case "unavailable":
+      throw integrationError("INTEGRATION_UNAVAILABLE");
+    case "timeout":
+      throw integrationError("INTEGRATION_TIMEOUT");
+    case "available":
+      break;
+  }
+}
+function createMockAdapter(opts = {}) {
+  const items = opts.items ?? DEFAULT_ITEMS;
+  const defaultSim = opts.simulate ?? "available";
+  const defaultPageSize = opts.pageSize ?? 50;
+  return {
+    id: MOCK_ADAPTER_ID,
+    metadata: {
+      id: MOCK_ADAPTER_ID,
+      displayName: "Mock Work Source",
+      version: "1.0.0",
+      description: "Deterministic offline reference adapter for validating the integration foundation."
+    },
+    capabilities: {
+      workItems: { list: true, read: true, import: true, write: false, statusSync: false, comments: false, webhooks: false }
+    },
+    async verifyConnection(context) {
+      const sim = simulationOf(context, defaultSim);
+      const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+      switch (sim) {
+        case "available":
+          return { status: "available", checkedAt };
+        case "unauthorized":
+          return { status: "unauthorized", message: "Check the configured credentials.", checkedAt };
+        case "rate-limited":
+        case "unavailable":
+        case "timeout":
+          return { status: "unavailable", message: "The mock provider is temporarily unavailable.", checkedAt };
+      }
+    },
+    async listWorkItems(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      let pool = items;
+      const f = request.filters;
+      if (f?.status) pool = pool.filter((i) => (i.status ?? "").toLowerCase() === f.status.toLowerCase());
+      if (f?.query) pool = pool.filter((i) => `${i.title} ${i.description ?? ""}`.toLowerCase().includes(f.query.toLowerCase()));
+      if (f?.updatedSince) pool = pool.filter((i) => (i.updatedAt ?? "") >= f.updatedSince);
+      const size = Math.max(1, request.pageSize ?? defaultPageSize);
+      const start = request.cursor ? Math.max(0, Number.parseInt(request.cursor, 10) || 0) : 0;
+      const slice = pool.slice(start, start + size);
+      const end = start + slice.length;
+      const hasMore = end < pool.length;
+      return { items: slice, hasMore, ...hasMore ? { nextCursor: String(end) } : {} };
+    },
+    async getWorkItem(request) {
+      readFailure(simulationOf(request.context, defaultSim));
+      return items.find((i) => i.externalId === request.externalId) ?? null;
+    }
+  };
+}
+
+// ../integrations/src/index.ts
+function createDefaultRegistry() {
+  const registry2 = new IntegrationRegistry();
+  registry2.register(createMockAdapter());
+  return registry2;
+}
+
+// src/services/integrations.ts
+var INTEGRATIONS_FILE = ".kaddo/integrations.yml";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var registry = createDefaultRegistry();
+var IntegrationServiceError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "IntegrationServiceError";
+    this.code = code;
+  }
+};
+function loadRaw(dir) {
+  const abs = join(dir, INTEGRATIONS_FILE);
+  if (!exists(abs)) return { integrations: [] };
+  try {
+    return parseYaml17(readFile(abs)) ?? { integrations: [] };
+  } catch {
+    return { integrations: [] };
+  }
+}
+function loadIntegrations(dir) {
+  return parseIntegrationsConfig(loadRaw(dir), { adapterIds: registry.ids() });
+}
+function configStatus(integration, findings) {
+  if (!integration.enabled) return "disabled";
+  const blocking = findings.some((f) => f.id === integration.id && f.level === "blocking");
+  if (blocking || !registry.has(integration.adapter)) return "invalid-config";
+  return "configured";
+}
+function listIntegrations(dir) {
+  const { integrations, findings } = loadIntegrations(dir);
+  return integrations.map((integration) => {
+    const adapter = registry.get(integration.adapter);
+    return {
+      id: integration.id,
+      adapter: integration.adapter,
+      enabled: integration.enabled,
+      status: configStatus(integration, findings),
+      displayName: adapter?.metadata.displayName ?? integration.adapter,
+      capabilities: adapter?.capabilities ?? null,
+      metadata: adapter?.metadata ?? null,
+      credentialRefs: Object.values(integration.credentials).map((c) => c.env),
+      findings: findings.filter((f) => f.id === integration.id)
+    };
+  });
+}
+function requireIntegration(dir, id) {
+  const { integrations, findings } = loadIntegrations(dir);
+  const integration = integrations.find((i) => i.id === id);
+  if (!integration) throw new IntegrationServiceError("INTEGRATION_NOT_CONFIGURED", `No integration "${id}" is configured in this project.`);
+  return { integration, findings };
+}
+function resolveAdapter(integration) {
+  const adapter = registry.get(integration.adapter);
+  if (!adapter) throw new IntegrationServiceError("ADAPTER_NOT_FOUND", `Unknown integration adapter "${integration.adapter}".`);
+  return adapter;
+}
+function buildContext(integration, env) {
+  const { credentials, missing } = resolveCredentials(integration, env);
+  return {
+    context: { integrationId: integration.id, config: integration.config, credentials, timeoutMs: integration.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+    missing
+  };
+}
+async function withTimeout(op, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(integrationError("INTEGRATION_TIMEOUT")), ms);
+  });
+  try {
+    return await Promise.race([op, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function verifyIntegration(dir, id, env = process.env) {
+  const { integration, findings } = requireIntegration(dir, id);
+  const cfgStatus = configStatus(integration, findings);
+  if (cfgStatus === "disabled") return { id, status: "disabled", connection: null, missingCredentials: [] };
+  if (cfgStatus === "invalid-config") return { id, status: "invalid-config", connection: null, missingCredentials: [] };
+  const adapter = resolveAdapter(integration);
+  const { context, missing } = buildContext(integration, env);
+  try {
+    const connection = await withTimeout(adapter.verifyConnection(context), context.timeoutMs);
+    return { id, status: statusOf(connection), connection, missingCredentials: missing, message: connection.message };
+  } catch (err) {
+    const e = err instanceof IntegrationError ? err : integrationError("INTEGRATION_PROVIDER_ERROR");
+    return { id, status: e.code === "INTEGRATION_UNAUTHORIZED" ? "unauthorized" : "unavailable", connection: null, missingCredentials: missing, message: e.safeMessage };
+  }
+}
+function statusOf(connection) {
+  switch (connection.status) {
+    case "available":
+      return "available";
+    case "unauthorized":
+      return "unauthorized";
+    case "unavailable":
+      return "unavailable";
+    case "invalid-config":
+      return "invalid-config";
+  }
+}
+async function listExternalWorkItems(dir, id, opts = {}, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.list) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot list work items.`);
+  const { context } = buildContext(integration, env);
+  return withTimeout(adapter.listWorkItems({ context, cursor: opts.cursor, pageSize: opts.pageSize, filters: opts.filters }), context.timeoutMs);
+}
+async function getExternalWorkItem(dir, id, externalId, env = process.env) {
+  const { integration } = requireIntegration(dir, id);
+  const adapter = resolveAdapter(integration);
+  if (!adapter.capabilities.workItems.read) throw integrationError("UNSUPPORTED_CAPABILITY", `Adapter "${adapter.id}" cannot read work items.`);
+  const { context } = buildContext(integration, env);
+  return withTimeout(adapter.getWorkItem({ context, externalId }), context.timeoutMs);
+}
+function findLinkedWorkItem(dir, integrationId, externalId) {
+  for (const art of discoverWorkItems(dir)) {
+    let data;
+    try {
+      data = matter11(readFile(art.filePath)).data;
+    } catch {
+      continue;
+    }
+    const source = parseWorkItemSource(data);
+    if (source.integration === integrationId && source.id === externalId) {
+      return { workItemId: String(data.id ?? ""), title: String(data.title ?? "") };
+    }
+  }
+  return null;
+}
+async function previewImport(dir, id, externalId, opts = {}, env = process.env) {
+  const item = await getExternalWorkItem(dir, id, externalId, env);
+  if (!item) throw integrationError("INTEGRATION_NOT_FOUND", `External work item "${externalId}" was not found.`);
+  const preview = buildImportPreview(item, { integrationId: id, type: opts.type });
+  return { preview, duplicate: findLinkedWorkItem(dir, id, externalId) };
+}
+async function importExternalWorkItem(dir, id, externalId, opts, env = process.env) {
+  const item = await getExternalWorkItem(dir, id, externalId, env);
+  if (!item) throw integrationError("INTEGRATION_NOT_FOUND", `External work item "${externalId}" was not found.`);
+  const preview = buildImportPreview(item, { integrationId: id, type: opts.type });
+  const existing = findLinkedWorkItem(dir, id, externalId);
+  if (existing) return { workItemId: existing.workItemId, created: false, duplicateOf: existing.workItemId, preview };
+  const intent = item.description ? `${item.title}
+
+${item.description}` : item.title;
+  const created = createWorkItem(dir, {
+    intent,
+    type: opts.type,
+    source: {
+      type: "external",
+      provider: item.provider,
+      integration: id,
+      id: externalId,
+      url: item.url,
+      imported_at: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  });
+  return { workItemId: created.id, created: true, preview, path: created.path };
+}
+
+// src/commands/integrations.ts
+function requireProject2(dir) {
+  if (!loadConfig(dir)) {
+    log2.error("No Kaddo project was found in the current directory.");
+    process.exit(1);
+  }
+}
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function fail(err) {
+  if (err instanceof IntegrationError) log2.error(`[${err.code}] ${err.safeMessage}`);
+  else if (err instanceof IntegrationServiceError) log2.error(`[${err.code}] ${err.message}`);
+  else log2.error("The integration operation failed.");
+  process.exit(1);
+}
+function runIntegrationsList(dir, opts) {
+  requireProject2(dir);
+  const items = listIntegrations(dir);
+  if (opts.json) return printJson(items.map((i) => ({ id: i.id, adapter: i.adapter, enabled: i.enabled, status: i.status, capabilities: i.capabilities })));
+  intro2("Kaddo integrations");
+  if (items.length === 0) {
+    log2.info("No integrations are configured. Add them to .kaddo/integrations.yml.");
+    return outro2("Done.");
+  }
+  for (const i of items) {
+    log2.info(`${i.id} \xB7 adapter ${i.adapter} \xB7 ${i.status}${i.enabled ? "" : " (disabled)"}`);
+    if (i.capabilities) log2.message(`  read: ${i.capabilities.workItems.read ? "\u2713" : "\u2717"}  list: ${i.capabilities.workItems.list ? "\u2713" : "\u2717"}  import: ${i.capabilities.workItems.import ? "\u2713" : "\u2717"}`);
+    for (const f of i.findings) log2.warn(`  [${f.level}] ${f.message}`);
+  }
+  outro2("Done.");
+}
+async function runIntegrationsStatus(dir, opts) {
+  requireProject2(dir);
+  const summaries = listIntegrations(dir);
+  const results = await Promise.all(summaries.map(async (s) => {
+    if (s.status === "disabled" || s.status === "invalid-config") return { id: s.id, status: s.status };
+    try {
+      const v = await verifyIntegration(dir, s.id);
+      return { id: s.id, status: v.status, message: v.message, missingCredentials: v.missingCredentials };
+    } catch (err) {
+      return { id: s.id, status: "unavailable", message: err instanceof IntegrationError ? err.safeMessage : "Verification failed." };
+    }
+  }));
+  if (opts.json) return printJson(results);
+  intro2("Integration status");
+  for (const r of results) {
+    const line = `${r.id} \xB7 ${r.status}${r.message ? ` \u2014 ${r.message}` : ""}`;
+    if (r.status === "available" || r.status === "configured") log2.info(line);
+    else log2.warn(line);
+  }
+  outro2("Done.");
+}
+async function runIntegrationsVerify(dir, id, opts) {
+  requireProject2(dir);
+  try {
+    const v = await verifyIntegration(dir, id);
+    if (opts.json) return printJson({ id: v.id, status: v.status, message: v.message, missingCredentials: v.missingCredentials });
+    intro2(`Verify ${id}`);
+    const line = `Status: ${v.status}${v.message ? ` \u2014 ${v.message}` : ""}`;
+    if (v.status === "available") log2.info(line);
+    else log2.warn(line);
+    if (v.missingCredentials.length) log2.warn(`Missing credentials: ${v.missingCredentials.join(", ")}`);
+    outro2("Done.");
+  } catch (err) {
+    fail(err);
+  }
+}
+async function runIntegrationsWorkItems(dir, id, opts) {
+  requireProject2(dir);
+  try {
+    const page = await listExternalWorkItems(dir, id, {
+      cursor: opts.cursor,
+      pageSize: opts.pageSize ? Number.parseInt(opts.pageSize, 10) : void 0,
+      filters: { status: opts.status, query: opts.query }
+    });
+    if (opts.json) return printJson(page);
+    intro2(`External work items \xB7 ${id}`);
+    for (const it of page.items) log2.info(`${it.externalId} \xB7 ${it.title}${it.status ? ` [${it.status}]` : ""}`);
+    if (page.hasMore) log2.message(`More available \u2014 next cursor: ${page.nextCursor}`);
+    outro2(`${page.items.length} item(s).`);
+  } catch (err) {
+    fail(err);
+  }
+}
+async function runIntegrationsWorkItem(dir, id, externalId, opts) {
+  requireProject2(dir);
+  try {
+    const item = await getExternalWorkItem(dir, id, externalId);
+    if (!item) {
+      log2.error(`External work item "${externalId}" was not found.`);
+      process.exit(1);
+    }
+    if (opts.json) return printJson(item);
+    intro2(`${item.provider} \xB7 ${item.externalId}`);
+    log2.info(item.title);
+    if (item.status) log2.message(`Status: ${item.status}`);
+    if (item.type) log2.message(`Type: ${item.type}`);
+    if (item.url) log2.message(`URL: ${item.url}`);
+    if (item.description) log2.message(`
+${item.description}`);
+    outro2("Done.");
+  } catch (err) {
+    fail(err);
+  }
+}
+async function runIntegrationsImport(dir, id, externalId, opts) {
+  requireProject2(dir);
+  try {
+    const { preview, duplicate } = await previewImport(dir, id, externalId, { type: opts.type });
+    intro2("Import external work item");
+    if (duplicate) {
+      log2.warn(`Already imported as ${duplicate.workItemId} \u2014 "${duplicate.title}".`);
+      outro2("No duplicate was created.");
+      return;
+    }
+    log2.info(`Source: ${preview.source.provider} \xB7 ${preview.source.externalId}`);
+    log2.message(`Captured intent: ${preview.capturedIntent}`);
+    log2.message("Will create: a Draft Work Item (needs refinement).");
+    if (preview.externalType) log2.message(`External type: ${preview.externalType} (Kaddo type is chosen, never inferred)`);
+    log2.message("No project files have been modified yet.");
+    if (!opts.type) {
+      log2.error("A Kaddo Work Item type is required. Re-run with --type <feature|fix|chore|\u2026>.");
+      process.exit(1);
+    }
+    if (!opts.yes) {
+      const ok = await confirm2({ message: `Import ${preview.source.displayKey} as a Draft ${opts.type} Work Item?` });
+      if (ok !== true) {
+        cancel2("Import cancelled. No files were changed.");
+        process.exit(0);
+      }
+    }
+    const result = await importExternalWorkItem(dir, id, externalId, { type: opts.type });
+    if (!result.created) {
+      log2.warn(`Already imported as ${result.duplicateOf}.`);
+      outro2("No duplicate was created.");
+      return;
+    }
+    log2.info(`Created ${result.workItemId} (Draft, needs refinement).`);
+    outro2("Done. Refine it next with the Work Item refinement handoff.");
+  } catch (err) {
+    fail(err);
+  }
+}
+
+// src/core/impact-report.ts
+import matter12 from "gray-matter";
 function isBroadGlob(glob) {
   if (!glob.endsWith("/**")) return false;
   const prefix = glob.slice(0, -3);
@@ -17448,7 +18213,7 @@ function buildImpactReport(dir, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
     try {
-      const body = matter10(readFile(wi.filePath)).content;
+      const body = matter12(readFile(wi.filePath)).content;
       if (hasSection(body, /acceptance|criterios de aceptaci/i)) withAcceptance++;
       else gaps.missing_acceptance_criteria.push(gapItem(wi, "Add an `## Acceptance Criteria` section."));
       if (hasSection(body, /definition of done|^#{1,6}\s*dod\b|definici[oó]n de (terminado|hecho)/i)) withDoD++;
@@ -17825,7 +18590,7 @@ function runReportImpact(opts = {}) {
 }
 
 // src/core/savings.ts
-import { parse as parseYaml17 } from "yaml";
+import { parse as parseYaml18 } from "yaml";
 var DEFAULT_ASSUMPTIONS = {
   currency: "USD",
   hourly_cost: 40,
@@ -17843,7 +18608,7 @@ function loadAssumptions(dir) {
   const p2 = join(dir, SAVINGS_PATH);
   if (!exists(p2)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
   try {
-    const raw = parseYaml17(readFile(p2));
+    const raw = parseYaml18(readFile(p2));
     const a = raw?.assumptions ?? {};
     const t = raw?.team ?? {};
     const num = (v, d) => typeof v === "number" && Number.isFinite(v) ? v : d;
@@ -18525,7 +19290,7 @@ function runAdr(opts = {}) {
 }
 
 // src/commands/tech.ts
-import fs4 from "fs";
+import fs5 from "fs";
 var DISCOVERY_FILES = ["architecture-notes.md", "decision-candidates.md"];
 var DISCOVERY_DIR = "knowledge/tech/discovery";
 function runTechOrganize(dir = cwd()) {
@@ -18542,7 +19307,7 @@ function runTechOrganize(dir = cwd()) {
       continue;
     }
     ensureDir(join(dir, DISCOVERY_DIR));
-    fs4.renameSync(from, to);
+    fs5.renameSync(from, to);
     moved.push(`knowledge/tech/${file} \u2192 ${DISCOVERY_DIR}/${file}`);
   }
   if (moved.length > 0) {
@@ -18624,9 +19389,9 @@ function runAssetsUpdate(kind, opts = {}) {
 }
 
 // src/commands/ready.ts
-import fs5 from "fs";
-import path8 from "path";
-import matter11 from "gray-matter";
+import fs6 from "fs";
+import path9 from "path";
+import matter13 from "gray-matter";
 function validateReadiness(content, frontmatter) {
   const warnings = [];
   const body = content.replace(/^---[\s\S]*?---/, "").trim();
@@ -18680,18 +19445,18 @@ function isResolvedSection(text3) {
 }
 function transitionToReady(filePath) {
   const raw = readFile(filePath);
-  const { data, content } = matter11(raw);
+  const { data, content } = matter13(raw);
   const today2 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   data.status = "ready";
   data.ready_at = today2;
-  const newContent = matter11.stringify(content, data);
+  const newContent = matter13.stringify(content, data);
   const posix = filePath.replace(/\\/g, "/");
   let newPath = filePath;
   if (posix.includes("/work-items/draft/")) {
-    const readyDir = path8.dirname(filePath).replace(/[/\\]draft$/, path8.sep + "ready");
+    const readyDir = path9.dirname(filePath).replace(/[/\\]draft$/, path9.sep + "ready");
     ensureDir(readyDir);
-    const fileName = path8.basename(filePath);
-    newPath = path8.join(readyDir, fileName);
+    const fileName = path9.basename(filePath);
+    newPath = path9.join(readyDir, fileName);
   }
   return { newPath, newContent };
 }
@@ -18724,7 +19489,7 @@ async function runReady(id, opts = {}) {
     process.exit(1);
   }
   const raw = readFile(wi.filePath);
-  const { data } = matter11(raw);
+  const { data } = matter13(raw);
   const source = parseWorkItemSource(data);
   const warnings = validateReadiness(raw, data);
   log2.info(`Work Item found:`);
@@ -18759,11 +19524,11 @@ async function runReady(id, opts = {}) {
   const { newPath, newContent } = transitionToReady(wi.filePath);
   if (newPath !== wi.filePath) {
     writeFile(newPath, newContent);
-    fs5.unlinkSync(wi.filePath);
+    fs6.unlinkSync(wi.filePath);
     log2.success(`Updated status: ready`);
     log2.success(`Moved file:`);
-    log2.info(`  ${path8.relative(dir, wi.filePath)}`);
-    log2.info(`  \u2192 ${path8.relative(dir, newPath)}`);
+    log2.info(`  ${path9.relative(dir, wi.filePath)}`);
+    log2.info(`  \u2192 ${path9.relative(dir, newPath)}`);
   } else {
     writeFile(wi.filePath, newContent);
     log2.success(`Updated status: ready`);
@@ -18774,7 +19539,7 @@ async function runReady(id, opts = {}) {
 }
 
 // src/commands/admin.ts
-import path9 from "path";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import net from "net";
 function isPortAvailable(port, host) {
@@ -18789,13 +19554,13 @@ function isPortAvailable(port, host) {
   });
 }
 function resolveStaticDir() {
-  const __dirname = path9.dirname(fileURLToPath2(import.meta.url));
+  const __dirname = path10.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
     // Bundled inside CLI dist (npm install)
-    path9.resolve(__dirname, "admin-dist"),
+    path10.resolve(__dirname, "admin-dist"),
     // Monorepo development
-    path9.resolve(__dirname, "..", "..", "admin", "dist"),
-    path9.resolve(__dirname, "..", "node_modules", "@kaddo", "admin", "dist")
+    path10.resolve(__dirname, "..", "..", "admin", "dist"),
+    path10.resolve(__dirname, "..", "node_modules", "@kaddo", "admin", "dist")
   ];
   for (const c of candidates) {
     if (exists(join(c, "index.html"))) return c;
@@ -18837,8 +19602,8 @@ async function runAdmin(opts = {}) {
   }
   let adminServer;
   try {
-    const __dirname = path9.dirname(fileURLToPath2(import.meta.url));
-    const bundled = path9.resolve(__dirname, "admin-server", "index.js");
+    const __dirname = path10.dirname(fileURLToPath2(import.meta.url));
+    const bundled = path10.resolve(__dirname, "admin-server", "index.js");
     if (exists(bundled)) {
       const { pathToFileURL } = await import("url");
       adminServer = await import(pathToFileURL(bundled).href);
@@ -18917,8 +19682,8 @@ var capsuleCmd = program.command("capsule").description("Export this project as
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").option("--scope <scope>", 'Export scope: "system" includes all mapped modules').option("--module <id>", "Export a capsule for a specific mapped module").action((opts) => {
   runCapsuleExport(opts);
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path10) => {
-  runCapsuleAdd(path10);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path11) => {
+  runCapsuleAdd(path11);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
@@ -18931,6 +19696,23 @@ topologyCmd.command("validate <file>").description("Validate a topology proposal
 topologyCmd.command("apply <file>").description("Apply a validated topology proposal to the canonical artifact after human confirmation").option("-y, --yes", "Skip the confirmation prompt (for already-approved automation)").action((file, opts) => {
   runTopologyApply(file, opts);
 });
+var integrationsCmd = program.command("integrations").description("Connect Kaddo to external work systems (read-first; import requires human confirmation)");
+integrationsCmd.command("list").description("List configured integrations and their capabilities").option("--json", "Output JSON").action((opts) => runIntegrationsList(cwd(), opts));
+integrationsCmd.command("status").description("Verify each enabled integration and report its connection status").option("--json", "Output JSON").action(async (opts) => {
+  await runIntegrationsStatus(cwd(), opts);
+});
+integrationsCmd.command("verify <id>").description("Verify one integration can actually connect (distinguishes configured from usable)").option("--json", "Output JSON").action(async (id, opts) => {
+  await runIntegrationsVerify(cwd(), id, opts);
+});
+integrationsCmd.command("work-items <id>").description("List external work items from an integration (paginated, read-only)").option("--json", "Output JSON").option("--cursor <cursor>", "Pagination cursor from a previous page").option("--page-size <n>", "Items per page").option("--status <status>", "Filter by external status").option("--query <text>", "Free-text filter").action(async (id, opts) => {
+  await runIntegrationsWorkItems(cwd(), id, opts);
+});
+integrationsCmd.command("work-item <id> <external-id>").description("Read a single external work item (read-only)").option("--json", "Output JSON").action(async (id, externalId, opts) => {
+  await runIntegrationsWorkItem(cwd(), id, externalId, opts);
+});
+integrationsCmd.command("import <id> <external-id>").description("Preview and, after confirmation, import an external work item as a Draft Work Item").option("--type <type>", "Kaddo Work Item type (required to create; never inferred from the external type)").option("-y, --yes", "Skip the confirmation prompt (for already-approved automation)").action(async (id, externalId, opts) => {
+  await runIntegrationsImport(cwd(), id, externalId, opts);
+});
 var reportCmd = program.command("report").description("Generate Kaddo reports");
 reportCmd.command("impact").description("Knowledge Impact Report: knowledge health, coverage, traceability, readiness (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--scope <scope>", "Scope: all (default \u2014 accumulated impact) or active").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/impact-report.md)").action((opts) => {
   runReportImpact(opts);