@kaddo/cli 3.78.0 → 3.80.0

package/dist/core.js

@@ -116,8 +116,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path3 = i.path.join(".");
-      return path3 ? `  - ${path3}: ${i.message}` : `  - ${i.message}`;
+      const path4 = i.path.join(".");
+      return path4 ? `  - ${path4}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -352,11 +352,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path3 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path3)) return [];
+  const path4 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path4)) return [];
   let parsed;
   try {
-    parsed = parseYaml3(readFile(path3));
+    parsed = parseYaml3(readFile(path4));
   } catch {
     return [];
   }
@@ -1590,7 +1590,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path3, md) {
+function parseCapsule(id, path4, md) {
   const { data } = matter2(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -1600,7 +1600,7 @@ function parseCapsule(id, path3, md) {
   }
   return {
     id,
-    path: path3,
+    path: path4,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -1662,9 +1662,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer of layerDocs) {
-    const path3 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path3) {
-      addNode({ id: layer.id, type: layer.type, label: layer.label, path: path3 });
+    const path4 = layer.files.map((f) => `${KNOWLEDGE2}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path4) {
+      addNode({ id: layer.id, type: layer.type, label: layer.label, path: path4 });
       presentLayers.push(layer.id);
     }
   }
@@ -3060,10 +3060,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 path3 = agentInstallPath(file);
-    const installed = isFile(join(dir, path3));
+    const path4 = agentInstallPath(file);
+    const installed = isFile(join(dir, path4));
     const group = agentGroupOf(file);
-    return { agentPath: path3, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+    return { agentPath: path4, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
   };
   const moduleRepo = isModule(config);
   const coreRepo = isCore(config);
@@ -7752,6 +7752,265 @@ function analyzeCrossRepoEvidence(input) {
 
 // src/core/work-items.ts
 import matter6 from "gray-matter";
+
+// src/core/system-topology.ts
+import { parse as parseYaml8, stringify as stringifyYaml4 } from "yaml";
+import fs2 from "fs";
+import path2 from "path";
+import crypto from "crypto";
+var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
+var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
+  "system",
+  "application",
+  "service",
+  "component",
+  "api",
+  "interface",
+  "datastore",
+  "queue",
+  "job",
+  "external-system",
+  "module",
+  "unknown"
+]);
+var TECHNICAL_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set([
+  "contains",
+  "depends-on",
+  "calls",
+  "reads-from",
+  "writes-to",
+  "publishes-to",
+  "subscribes-to",
+  "integrates-with",
+  "runs-on",
+  "implemented-by"
+]);
+var PROVENANCE = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewed"]);
+function isRelative(p2) {
+  return typeof p2 === "string" && p2.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p2) && !p2.includes("..");
+}
+function strList(v) {
+  return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
+}
+function loadSystemTopology(dir) {
+  const filePath = join(dir, TOPOLOGY_FILE);
+  if (!exists(filePath)) return { entities: [], relationships: [], findings: [], declared: false };
+  const parsed = parseTopologyContent(readFile(filePath), dir);
+  return { ...parsed, declared: true };
+}
+function parseTopologyContent(raw, dir) {
+  let parsed;
+  try {
+    parsed = parseYaml8(raw) ?? {};
+  } catch {
+    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "The topology could not be parsed." }] };
+  }
+  const sourceRevision = typeof parsed.source_revision === "string" ? parsed.source_revision : void 0;
+  const findings = [];
+  const validModules = /* @__PURE__ */ new Set(["core", ...loadMappedModules(dir).map((m) => m.id)]);
+  const rawEntities = Array.isArray(parsed.entities) ? parsed.entities : [];
+  const entities = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const raw2 of rawEntities) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const e = raw2;
+    const id = typeof e.id === "string" ? e.id.trim() : "";
+    if (!id) {
+      findings.push({ level: "warning", message: "A topology entity is missing an id and was skipped." });
+      continue;
+    }
+    if (seenIds.has(id)) {
+      findings.push({ level: "blocking", message: `Duplicate topology entity id "${id}".` });
+      continue;
+    }
+    const kind = typeof e.kind === "string" ? e.kind.trim() : "unknown";
+    if (!SYSTEM_ENTITY_KINDS.has(kind)) {
+      findings.push({ level: "warning", message: `Entity "${id}" has an unknown kind "${kind}"; treated as unknown.` });
+    }
+    const moduleRaw = typeof e.module === "string" ? e.module.trim() : void 0;
+    if (moduleRaw && !validModules.has(moduleRaw)) findings.push({ level: "warning", message: `Entity "${id}" references unregistered module "${moduleRaw}".` });
+    const rawImpl = e.implementation ?? e.implementation_refs;
+    const implementation = strList(rawImpl).filter((p2) => {
+      if (isRelative(p2)) return true;
+      findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p2}" is not a safe relative path and was dropped.` });
+      return false;
+    });
+    const prov = e.provenance;
+    const provOrigin = typeof prov === "string" ? prov : prov && typeof prov === "object" && typeof prov.origin === "string" ? String(prov.origin) : void 0;
+    const provenance = provOrigin && PROVENANCE.has(provOrigin) ? provOrigin : void 0;
+    const evidence = strList(e.evidence ?? (prov && typeof prov === "object" ? prov.evidence_refs : void 0)).filter(isRelative);
+    seenIds.add(id);
+    entities.push({
+      id,
+      kind: SYSTEM_ENTITY_KINDS.has(kind) ? kind : "unknown",
+      label: typeof e.label === "string" && e.label.trim() ? e.label.trim() : id,
+      ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
+      ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
+      implementationRefs: implementation,
+      knowledgeRefs: strList(e.knowledge ?? e.knowledge_refs),
+      ...provenance ? { provenance } : {},
+      evidence
+    });
+  }
+  const entityIds = new Set(entities.map((e) => e.id));
+  const rawRels = Array.isArray(parsed.relationships) ? parsed.relationships : [];
+  const relationships = [];
+  const seenRels = /* @__PURE__ */ new Set();
+  for (const raw2 of rawRels) {
+    if (!raw2 || typeof raw2 !== "object") continue;
+    const r = raw2;
+    const from = typeof r.from === "string" ? r.from.trim() : typeof r.source === "string" ? r.source.trim() : "";
+    const to = typeof r.to === "string" ? r.to.trim() : typeof r.target === "string" ? r.target.trim() : "";
+    const type = typeof r.type === "string" ? r.type.trim() : "";
+    if (!from || !to || !type) {
+      findings.push({ level: "warning", message: "A topology relationship is missing from/to/type and was skipped." });
+      continue;
+    }
+    if (!TECHNICAL_RELATIONSHIP_TYPES.has(type)) {
+      findings.push({ level: "warning", message: `Relationship type "${type}" is not recognized and was skipped.` });
+      continue;
+    }
+    if (!entityIds.has(from) || !entityIds.has(to)) {
+      findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
+      continue;
+    }
+    const key = `${from}~${type}~${to}`;
+    if (seenRels.has(key)) {
+      findings.push({ level: "warning", message: `Duplicate relationship ${from} ${type} ${to} was skipped.` });
+      continue;
+    }
+    seenRels.add(key);
+    const prov = r.provenance;
+    relationships.push({ from, to, type, evidence: strList(r.evidence ?? prov?.evidence_refs).filter(isRelative) });
+  }
+  return { entities, relationships, findings, ...sourceRevision ? { sourceRevision } : {} };
+}
+function validateSystemTopology(dir) {
+  return loadSystemTopology(dir).findings;
+}
+var TopologyWriteError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopologyWriteError";
+    this.code = code;
+  }
+};
+function topologyRevision(dir) {
+  const filePath = join(dir, TOPOLOGY_FILE);
+  const raw = exists(filePath) ? readFile(filePath) : "";
+  return crypto.createHash("sha256").update(raw, "utf-8").digest("hex");
+}
+function validateTopologyProposal(dir, proposalYaml) {
+  const { entities, relationships, findings } = parseTopologyContent(proposalYaml, dir);
+  const blocking = findings.filter((f) => f.level === "blocking").length;
+  const warning = findings.filter((f) => f.level === "warning").length;
+  return { findings, blocking, warning, canApply: blocking === 0, entityCount: entities.length, relationshipCount: relationships.length };
+}
+function serializeTopology(entities, relationships) {
+  const doc = {
+    entities: entities.map((e) => ({
+      id: e.id,
+      kind: e.kind,
+      label: e.label,
+      ...e.purpose ? { purpose: e.purpose } : {},
+      ...e.moduleId ? { module: e.moduleId } : {},
+      ...e.implementationRefs.length ? { implementation: e.implementationRefs } : {},
+      ...e.knowledgeRefs.length ? { knowledge: e.knowledgeRefs } : {},
+      ...e.provenance ? { provenance: e.provenance } : {},
+      ...e.evidence.length ? { evidence: e.evidence } : {}
+    })),
+    relationships: relationships.map((r) => ({ from: r.from, to: r.to, type: r.type, ...r.evidence.length ? { evidence: r.evidence } : {} }))
+  };
+  return stringifyYaml4(doc);
+}
+function atomicWrite(filePath, content) {
+  fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs2.writeFileSync(tmp, content, "utf-8");
+  try {
+    fs2.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs2.rmSync(tmp, { force: true });
+    } catch {
+    }
+    throw err;
+  }
+}
+function applyTopologyProposal(dir, proposalYaml, expectedRevision) {
+  const validation = validateTopologyProposal(dir, proposalYaml);
+  if (!validation.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The topology proposal has blocking findings and cannot be applied.");
+  const current = topologyRevision(dir);
+  if (expectedRevision != null && expectedRevision !== current) {
+    throw new TopologyWriteError("TOPOLOGY_CONFLICT", "The topology changed after this proposal was created. Refresh and validate the proposal again.");
+  }
+  const proposal = parseTopologyContent(proposalYaml, dir);
+  const existing = loadSystemTopology(dir);
+  const entityMap = /* @__PURE__ */ new Map();
+  for (const e of existing.entities) entityMap.set(e.id, e);
+  let entitiesNew = 0, entitiesUpdated = 0;
+  for (const e of proposal.entities) {
+    if (entityMap.has(e.id)) entitiesUpdated++;
+    else entitiesNew++;
+    entityMap.set(e.id, e);
+  }
+  const relKey = (r) => `${r.from}~${r.type}~${r.to}`;
+  const relMap = /* @__PURE__ */ new Map();
+  for (const r of existing.relationships) relMap.set(relKey(r), r);
+  let relationshipsNew = 0;
+  for (const r of proposal.relationships) {
+    if (!relMap.has(relKey(r))) relationshipsNew++;
+    relMap.set(relKey(r), r);
+  }
+  const raw = serializeTopology([...entityMap.values()], [...relMap.values()]);
+  const finalCheck = validateTopologyProposal(dir, raw);
+  if (!finalCheck.canApply) throw new TopologyWriteError("TOPOLOGY_INVALID", "The merged topology is invalid; no changes were written.");
+  atomicWrite(join(dir, TOPOLOGY_FILE), raw);
+  return { revision: topologyRevision(dir), entitiesNew, entitiesUpdated, relationshipsNew };
+}
+function buildTopologyEnrichmentHandoff(dir, projectName) {
+  const mappedModules = loadMappedModules(dir).map((m) => m.id);
+  const lines = [
+    `Enrich the semantic system topology for the Kaddo project "${projectName}".`,
+    "",
+    "Use the canonical architecture-agent and graph-metadata-review skill (via Kaddo MCP or skills).",
+    "Inspect the actual repository and relevant mapped modules \u2014 do not infer architecture from",
+    "filenames or directory names."
+  ];
+  if (mappedModules.length > 0) {
+    lines.push("", `This is a multirepo project. Inspect the relevant mapped modules (${mappedModules.join(", ")}) before finalizing the topology.`);
+  }
+  lines.push(
+    "",
+    "Build a topology PROPOSAL first \u2014 do not write canonical metadata directly. For each entity",
+    "capture, only when supported by evidence:",
+    "- a stable id and semantic kind (application/service/component/api/interface/datastore/queue/job/external-system);",
+    "- a responsibility/purpose (what it does, not how);",
+    "- the owning module/repository;",
+    "- implementation references (relative paths);",
+    "- relevant Knowledge references (capability/ADR ids), not Kaddo operational assets;",
+    "- provenance/evidence.",
+    "",
+    "Capture evidence-backed technical relationships: contains, calls, depends-on, reads-from,",
+    "writes-to, integrates-with, runs-on. Preserve Unknown when evidence is insufficient.",
+    "",
+    "Validate the proposal through Kaddo before applying it. Do not write canonical topology metadata",
+    `unless (1) Kaddo validation succeeds and (2) the human explicitly confirms the write. The canonical`,
+    `artifact is ${TOPOLOGY_FILE}; Core validates and applies it \u2014 do not hand-edit it.`,
+    "",
+    "Do not implement application changes. Do not run mutating Git operations."
+  );
+  return {
+    projectName,
+    recommendedAgent: "architecture-agent",
+    recommendedSkill: "graph-metadata-review",
+    targetFile: TOPOLOGY_FILE,
+    text: lines.join("\n")
+  };
+}
+
+// src/core/work-items.ts
 function computeRefinementStatus(wi) {
   const aspects = {
     outcome: Boolean(wi.currentBehavior?.trim() || wi.targetBehavior?.trim()),
@@ -7858,10 +8117,23 @@ function getWorkItem(dir, workItemId) {
     decisions: parseDecisions(match.decisions, knowledgeById),
     relatedKnowledge: parseRelatedKnowledge(fm, knowledgeById),
     source: parseWorkItemSource(fm),
-    path: match.relPath
+    path: match.relPath,
+    ...parseSystemImpact(dir, fm)
   };
   return { ...detail, refinement: computeRefinementStatus(detail) };
 }
+function parseSystemImpact(dir, fm) {
+  const topology = loadSystemTopology(dir);
+  const byId = new Map(topology.entities.map((e) => [e.id, e]));
+  const resolve = (id) => {
+    const e = byId.get(id);
+    return { id, nodeId: `sys:${id}`, label: e?.label ?? id, kind: e?.kind ?? "unknown", moduleId: e?.moduleId ?? null };
+  };
+  const affected = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(String).filter(Boolean).map(resolve) : [];
+  const reviewed = Array.isArray(fm.reviewed_system_entities) ? fm.reviewed_system_entities.filter((r) => Boolean(r) && typeof r === "object").map((r) => ({ ...resolve(String(r.id ?? "")), status: String(r.status ?? "unknown"), reason: r.reason ? String(r.reason) : null })).filter((r) => r.id) : [];
+  const graphRevision = typeof fm.graph_revision === "string" && fm.graph_revision.trim() ? fm.graph_revision.trim() : null;
+  return { affectedSystemEntities: affected, reviewedSystemEntities: reviewed, graphRevision };
+}
 function readBody(filePath) {
   try {
     const raw = readFile(filePath);
@@ -8029,9 +8301,9 @@ function parseRelatedKnowledge(fm, knowledgeById) {
 }
 
 // src/core/work-item-write.ts
-import fs2 from "fs";
-import path2 from "path";
-import crypto from "crypto";
+import fs3 from "fs";
+import path3 from "path";
+import crypto2 from "crypto";
 import matter7 from "gray-matter";
 
 // src/core/knowledge-levels.ts
@@ -8234,7 +8506,7 @@ var VALID_COVERAGE = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected
 var VALID_CONFIDENCE = /* @__PURE__ */ new Set(["high", "medium", "low"]);
 var EDITABLE_STATES = ["draft"];
 function revisionOf(raw) {
-  return crypto.createHash("sha256").update(raw, "utf-8").digest("hex");
+  return crypto2.createHash("sha256").update(raw, "utf-8").digest("hex");
 }
 function slugify2(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
@@ -8244,7 +8516,7 @@ function nextWorkItemId(dir) {
   let max = 0;
   const walk = (d) => {
     if (!exists(d)) return;
-    for (const entry of fs2.readdirSync(d)) {
+    for (const entry of fs3.readdirSync(d)) {
       const full = join(d, entry);
       if (isFile(full)) {
         const m = entry.match(/WI-(\d+)/);
@@ -8257,15 +8529,15 @@ function nextWorkItemId(dir) {
   walk(wiDir);
   return `WI-${String(max + 1).padStart(3, "0")}`;
 }
-function atomicWrite(filePath, content) {
-  fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+function atomicWrite2(filePath, content) {
+  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
   const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  fs2.writeFileSync(tmp, content, "utf-8");
+  fs3.writeFileSync(tmp, content, "utf-8");
   try {
-    fs2.renameSync(tmp, filePath);
+    fs3.renameSync(tmp, filePath);
   } catch (err) {
     try {
-      fs2.rmSync(tmp, { force: true });
+      fs3.rmSync(tmp, { force: true });
     } catch {
     }
     throw err;
@@ -8565,7 +8837,7 @@ function createWorkItem(dir, opts) {
   const filePath = join(dir, relPath);
   if (exists(filePath)) throw new WorkItemWriteError("INVALID_INPUT", `Work Item file already exists: ${relPath}`);
   const raw = serialize(data, body);
-  atomicWrite(filePath, raw);
+  atomicWrite2(filePath, raw);
   return { id, path: relPath, revision: revisionOf(raw) };
 }
 function validateInput(input) {
@@ -8587,7 +8859,7 @@ function updateWorkItem(dir, id, input, expectedRevision) {
   const nextData = applyFrontmatter(data, input);
   const nextBody = mergeBody(content, input);
   const nextRaw = serialize(nextData, nextBody);
-  atomicWrite(filePath, nextRaw);
+  atomicWrite2(filePath, nextRaw);
   return { revision: revisionOf(nextRaw), path: relPath };
 }
 function validateWorkItem(dir, id) {
@@ -8615,6 +8887,26 @@ function validateWorkItem(dir, id) {
   for (const s of input.impactAnalysis) {
     if (s.status === "unknown") findings.push({ level: "fyi", message: `Impact on ${s.surface} is unknown.` });
   }
+  const topology = loadSystemTopology(dir);
+  const entityById = new Map(topology.entities.map((e) => [e.id, e]));
+  const fm = data;
+  const affectedEntities = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(String) : [];
+  for (const eid of affectedEntities) {
+    const e = entityById.get(eid);
+    if (!e) {
+      findings.push({ level: "blocking", message: `Affected system entity "${eid}" does not exist in the semantic topology.` });
+      continue;
+    }
+    if (e.moduleId && !input.affectedModules.includes(e.moduleId)) {
+      findings.push({ level: "warning", message: `System entity "${e.label}" belongs to module "${e.moduleId}", which is not in affected_modules.` });
+    }
+  }
+  if (Array.isArray(fm.reviewed_system_entities)) {
+    for (const r of fm.reviewed_system_entities) {
+      const rid = r && typeof r === "object" ? String(r.id ?? "") : "";
+      if (rid && !entityById.has(rid)) findings.push({ level: "warning", message: `Reviewed system entity "${rid}" does not exist in the semantic topology.` });
+    }
+  }
   const canMarkReady = !findings.some((f) => f.level === "blocking");
   return { findings, canMarkReady };
 }
@@ -8636,235 +8928,19 @@ function transitionWorkItem(dir, id, to, expectedRevision) {
   }
   const nextData = { ...data, status: to };
   const nextRaw = serialize(nextData, content);
-  const filename = path2.basename(filePath);
+  const filename = path3.basename(filePath);
   const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
   const targetPath = join(dir, targetRel);
-  atomicWrite(targetPath, nextRaw);
-  if (path2.resolve(targetPath) !== path2.resolve(filePath)) {
+  atomicWrite2(targetPath, nextRaw);
+  if (path3.resolve(targetPath) !== path3.resolve(filePath)) {
     try {
-      fs2.rmSync(filePath, { force: true });
+      fs3.rmSync(filePath, { force: true });
     } catch {
     }
   }
   return { revision: revisionOf(nextRaw), status: to, path: targetRel };
 }
 
-// src/core/work-item-refinement.ts
-function toCapture(q) {
-  return { id: q.id, prompt: q.prompt, placeholder: q.placeholder, field: q.frontMatterField, required: q.required };
-}
-function getWorkItemCaptureDefinition() {
-  const questions = {};
-  for (const type of WORK_ITEM_TYPES2) {
-    questions[type] = getLevel(getLevelForType(type)).questions.map(toCapture);
-  }
-  return {
-    types: WORK_ITEM_TYPES2.map((t) => ({ value: t, label: t.charAt(0).toUpperCase() + t.slice(1) })),
-    questions
-  };
-}
-var RECOMMENDED_AGENT = "work-item-agent";
-var RECOMMENDED_SKILL = "work-item-refinement";
-function buildRefinementHandoff(dir, workItemId) {
-  const wi = getWorkItem(dir, workItemId);
-  const config = loadConfig(dir);
-  const projectName = config?.project.name ?? "this project";
-  const mappedModules = loadMappedModules(dir).map((m) => m.id);
-  const multirepo = mappedModules.length > 0;
-  const lines = [
-    `Refine Work Item ${wi.id} \u2014 "${wi.title}" \u2014 in project "${projectName}" using Kaddo.`,
-    "",
-    "Use a Kaddo-enabled agent with access to this repository. Drive the refinement with the",
-    `canonical ${RECOMMENDED_AGENT} and the ${RECOMMENDED_SKILL} skill (via Kaddo MCP or skills).`,
-    "",
-    "Inspect the actual implementation before defining scope \u2014 do not guess affected modules from",
-    "the Work Item title. Read the current behavior in the code first, then classify."
-  ];
-  if (multirepo) {
-    lines.push(
-      "",
-      `This is a multirepo project. Evaluate the scope across all relevant mapped modules (${mappedModules.join(", ")})`,
-      "before finalizing affected_modules and module_coverage."
-    );
-  }
-  lines.push(
-    "",
-    `Update the canonical Work Item ${wi.id} with:`,
-    "- current and target behavior;",
-    "- the end-to-end flow (journey);",
-    "- affected modules;",
-    "- module coverage;",
-    "- impact analysis across the relevant surfaces;",
-    "- scope confidence and open unknowns;",
-    "- acceptance criteria;",
-    "- relevant Knowledge / ADR relationships.",
-    "",
-    "Do not implement the Work Item. Do not run mutating Git operations."
-  );
-  return {
-    workItemId: wi.id,
-    title: wi.title,
-    projectName,
-    refinement: wi.refinement,
-    recommendedAgent: RECOMMENDED_AGENT,
-    recommendedSkill: RECOMMENDED_SKILL,
-    text: lines.join("\n")
-  };
-}
-
-// src/core/system-topology.ts
-import { parse as parseYaml8 } from "yaml";
-var TOPOLOGY_FILE = "knowledge/tech/system-topology.yml";
-var SYSTEM_ENTITY_KINDS = /* @__PURE__ */ new Set([
-  "system",
-  "application",
-  "service",
-  "component",
-  "api",
-  "interface",
-  "datastore",
-  "queue",
-  "job",
-  "external-system",
-  "module",
-  "unknown"
-]);
-var TECHNICAL_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set([
-  "contains",
-  "depends-on",
-  "calls",
-  "reads-from",
-  "writes-to",
-  "publishes-to",
-  "subscribes-to",
-  "integrates-with",
-  "runs-on",
-  "implemented-by"
-]);
-var PROVENANCE = /* @__PURE__ */ new Set(["declared", "derived", "agent-reviewed"]);
-function isRelative(p2) {
-  return typeof p2 === "string" && p2.trim() !== "" && !/^([a-zA-Z]:[\\/]|\/)/.test(p2) && !p2.includes("..");
-}
-function strList(v) {
-  return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
-}
-function loadSystemTopology(dir) {
-  const path3 = join(dir, TOPOLOGY_FILE);
-  if (!exists(path3)) return { entities: [], relationships: [], findings: [], declared: false };
-  let parsed;
-  try {
-    parsed = parseYaml8(readFile(path3)) ?? {};
-  } catch {
-    return { entities: [], relationships: [], findings: [{ level: "blocking", message: "system-topology.yml could not be parsed." }], declared: true };
-  }
-  const findings = [];
-  const validModules = /* @__PURE__ */ new Set(["core", ...loadMappedModules(dir).map((m) => m.id)]);
-  const rawEntities = Array.isArray(parsed.entities) ? parsed.entities : [];
-  const entities = [];
-  const seenIds = /* @__PURE__ */ new Set();
-  for (const raw of rawEntities) {
-    if (!raw || typeof raw !== "object") continue;
-    const e = raw;
-    const id = typeof e.id === "string" ? e.id.trim() : "";
-    if (!id) {
-      findings.push({ level: "warning", message: "A topology entity is missing an id and was skipped." });
-      continue;
-    }
-    if (seenIds.has(id)) {
-      findings.push({ level: "blocking", message: `Duplicate topology entity id "${id}".` });
-      continue;
-    }
-    const kind = typeof e.kind === "string" ? e.kind.trim() : "unknown";
-    if (!SYSTEM_ENTITY_KINDS.has(kind)) {
-      findings.push({ level: "warning", message: `Entity "${id}" has an unknown kind "${kind}"; treated as unknown.` });
-    }
-    const moduleRaw = typeof e.module === "string" ? e.module.trim() : void 0;
-    if (moduleRaw && !validModules.has(moduleRaw)) findings.push({ level: "warning", message: `Entity "${id}" references unregistered module "${moduleRaw}".` });
-    const implementation = strList(e.implementation).filter((p2) => {
-      if (isRelative(p2)) return true;
-      findings.push({ level: "warning", message: `Entity "${id}" implementation ref "${p2}" is not a safe relative path and was dropped.` });
-      return false;
-    });
-    const provenance = typeof e.provenance === "string" && PROVENANCE.has(e.provenance) ? e.provenance : void 0;
-    seenIds.add(id);
-    entities.push({
-      id,
-      kind: SYSTEM_ENTITY_KINDS.has(kind) ? kind : "unknown",
-      label: typeof e.label === "string" && e.label.trim() ? e.label.trim() : id,
-      ...typeof e.purpose === "string" && e.purpose.trim() ? { purpose: e.purpose.trim() } : {},
-      ...moduleRaw && validModules.has(moduleRaw) ? { moduleId: moduleRaw } : {},
-      implementationRefs: implementation,
-      knowledgeRefs: strList(e.knowledge),
-      ...provenance ? { provenance } : {},
-      evidence: strList(e.evidence).filter(isRelative)
-    });
-  }
-  const entityIds = new Set(entities.map((e) => e.id));
-  const rawRels = Array.isArray(parsed.relationships) ? parsed.relationships : [];
-  const relationships = [];
-  for (const raw of rawRels) {
-    if (!raw || typeof raw !== "object") continue;
-    const r = raw;
-    const from = typeof r.from === "string" ? r.from.trim() : "";
-    const to = typeof r.to === "string" ? r.to.trim() : "";
-    const type = typeof r.type === "string" ? r.type.trim() : "";
-    if (!from || !to || !type) {
-      findings.push({ level: "warning", message: "A topology relationship is missing from/to/type and was skipped." });
-      continue;
-    }
-    if (!TECHNICAL_RELATIONSHIP_TYPES.has(type)) {
-      findings.push({ level: "warning", message: `Relationship type "${type}" is not recognized and was skipped.` });
-      continue;
-    }
-    if (!entityIds.has(from) || !entityIds.has(to)) {
-      findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
-      continue;
-    }
-    relationships.push({ from, to, type, evidence: strList(r.evidence).filter(isRelative) });
-  }
-  return { entities, relationships, findings, declared: true };
-}
-function validateSystemTopology(dir) {
-  return loadSystemTopology(dir).findings;
-}
-function buildTopologyEnrichmentHandoff(dir, projectName) {
-  const mappedModules = loadMappedModules(dir).map((m) => m.id);
-  const lines = [
-    `Enrich the semantic system topology for the Kaddo project "${projectName}".`,
-    "",
-    "Use the canonical architecture-agent and graph-metadata-review skill (via Kaddo MCP or skills).",
-    "Inspect the actual repository and relevant mapped modules \u2014 do not infer architecture from",
-    "filenames or directory names."
-  ];
-  if (mappedModules.length > 0) {
-    lines.push("", `This is a multirepo project. Inspect the relevant mapped modules (${mappedModules.join(", ")}) before finalizing the topology.`);
-  }
-  lines.push(
-    "",
-    `Write the result to ${TOPOLOGY_FILE} as declared entities and relationships. For each entity`,
-    "capture, only when supported by evidence:",
-    "- a stable id and semantic kind (application/service/component/api/interface/datastore/queue/job/external-system);",
-    "- a responsibility/purpose (what it does, not how);",
-    "- the owning module/repository;",
-    "- implementation references (relative paths);",
-    "- relevant Knowledge references (capability/ADR ids), not Kaddo operational assets.",
-    "",
-    "Capture evidence-backed technical relationships: contains, calls, depends-on, reads-from,",
-    "writes-to, integrates-with, runs-on. Preserve unknowns when evidence is insufficient.",
-    "",
-    "Review the proposed graph metadata (duplicate ids, dangling relationships, unknown modules,",
-    "invalid references) before writing.",
-    "Do not implement application changes. Do not run mutating Git operations."
-  );
-  return {
-    projectName,
-    recommendedAgent: "architecture-agent",
-    recommendedSkill: "graph-metadata-review",
-    targetFile: TOPOLOGY_FILE,
-    text: lines.join("\n")
-  };
-}
-
 // src/core/system-map.ts
 function dimensionOf(type) {
   switch (type) {
@@ -9046,6 +9122,118 @@ function getSystemNodeContext(dir, nodeId) {
   }
   return { node, incoming, outgoing };
 }
+var DEFAULT_MAX_DEPTH = 2;
+var DEFAULT_MAX_NODES = 50;
+function searchSystemNodes(dir, query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const rank = (n) => n.dimension === "system" ? 0 : n.dimension === "knowledge" ? 1 : n.dimension === "delivery" ? 2 : n.dimension === "unknown" ? 3 : 4;
+  return getSystemMapProjection(dir).nodes.filter(
+    (n) => n.label.toLowerCase().includes(q) || n.type.toLowerCase().includes(q) || (n.moduleId ?? "").toLowerCase().includes(q) || (n.purpose ?? "").toLowerCase().includes(q)
+  ).sort((a, b) => rank(a) - rank(b));
+}
+function getSystemNeighbors(dir, nodeId, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  if (!byId.has(nodeId)) return null;
+  const maxDepth = Math.max(1, opts.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const maxNodes = Math.max(1, opts.maxNodes ?? DEFAULT_MAX_NODES);
+  const relTypes = opts.relationshipTypes && opts.relationshipTypes.length ? new Set(opts.relationshipTypes) : null;
+  const modules = opts.moduleFilter && opts.moduleFilter.length ? new Set(opts.moduleFilter) : null;
+  const includeNode = (n) => !modules || n.moduleId != null && modules.has(n.moduleId) || n.id === nodeId;
+  const visited = /* @__PURE__ */ new Set([nodeId]);
+  const nodes = [];
+  const rels = [];
+  let frontier = [nodeId];
+  let truncated = false;
+  for (let depth = 0; depth < maxDepth && frontier.length > 0 && !truncated; depth++) {
+    const next = [];
+    for (const current of frontier) {
+      for (const r of projection.relationships) {
+        if (relTypes && !relTypes.has(r.type)) continue;
+        const other = r.source === current ? r.target : r.target === current ? r.source : null;
+        if (!other) continue;
+        const otherNode = byId.get(other);
+        if (!otherNode || !includeNode(otherNode)) continue;
+        if (!rels.some((x) => x.id === r.id)) rels.push(r);
+        if (!visited.has(other)) {
+          if (nodes.length >= maxNodes) {
+            truncated = true;
+            break;
+          }
+          visited.add(other);
+          nodes.push(otherNode);
+          next.push(other);
+        }
+      }
+      if (truncated) break;
+    }
+    frontier = next;
+  }
+  return { seed: nodeId, nodes, relationships: rels, truncated };
+}
+function findSystemPaths(dir, source, target, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  if (!byId.has(source) || !byId.has(target)) return [];
+  const maxDepth = Math.max(1, opts.maxDepth ?? 4);
+  const out = /* @__PURE__ */ new Map();
+  for (const r of projection.relationships) {
+    if (!out.has(r.source)) out.set(r.source, []);
+    out.get(r.source).push(r.target);
+  }
+  const paths = [];
+  const walk = (node, path4) => {
+    if (paths.length >= 20) return;
+    if (node === target && path4.length > 1) {
+      paths.push([...path4]);
+      return;
+    }
+    if (path4.length > maxDepth) return;
+    for (const nxt of out.get(node) ?? []) {
+      if (path4.includes(nxt)) continue;
+      walk(nxt, [...path4, nxt]);
+    }
+  };
+  walk(source, [source]);
+  return paths;
+}
+function getImpactCandidates(dir, seedIds, opts = {}) {
+  const projection = getSystemMapProjection(dir);
+  const byId = new Map(projection.nodes.map((n) => [n.id, n]));
+  const seeds = seedIds.filter((s) => byId.has(s));
+  const candidates = /* @__PURE__ */ new Map();
+  let truncated = false;
+  for (const seed of seeds) {
+    const neighborhood = getSystemNeighbors(dir, seed, opts);
+    if (!neighborhood) continue;
+    if (neighborhood.truncated) truncated = true;
+    for (const n of neighborhood.nodes) {
+      if (seeds.includes(n.id)) continue;
+      const rel = neighborhood.relationships.find((r) => r.source === seed && r.target === n.id || r.target === seed && r.source === n.id);
+      const reason = rel ? { relationship: rel.label, from: byId.get(rel.source)?.label ?? rel.source, to: byId.get(rel.target)?.label ?? rel.target } : { relationship: "related to", from: byId.get(seed)?.label ?? seed, to: n.label };
+      const existing = candidates.get(n.id);
+      if (existing) {
+        existing.reason.push(reason);
+        continue;
+      }
+      const path4 = findSystemPaths(dir, seed, n.id, { maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH })[0];
+      candidates.set(n.id, {
+        nodeId: n.id,
+        label: n.label,
+        kind: n.type,
+        ...n.moduleId ? { moduleId: n.moduleId } : {},
+        reason: [reason],
+        ...path4 ? { graphPath: path4.map((id) => byId.get(id)?.label ?? id) } : {},
+        ...n.implementationRefs?.length ? { implementationRefs: n.implementationRefs } : {},
+        ...n.knowledgeRefs?.length ? { knowledgeRefs: n.knowledgeRefs } : {},
+        status: "candidate",
+        provenance: { source: "graph-assisted" }
+      });
+    }
+  }
+  return { seeds, candidates: [...candidates.values()], truncated, topologyStatus: projection.metadata.topologyStatus };
+}
 function toNode(n, knowledgeByPath, wiModules, groupIds) {
   const node = { id: n.id, type: n.type, label: n.label, dimension: dimensionOf(n.type) };
   if (n.status) node.status = n.status;
@@ -9062,12 +9250,92 @@ function toNode(n, knowledgeByPath, wiModules, groupIds) {
   }
   return node;
 }
+
+// src/core/work-item-refinement.ts
+function toCapture(q) {
+  return { id: q.id, prompt: q.prompt, placeholder: q.placeholder, field: q.frontMatterField, required: q.required };
+}
+function getWorkItemCaptureDefinition() {
+  const questions = {};
+  for (const type of WORK_ITEM_TYPES2) {
+    questions[type] = getLevel(getLevelForType(type)).questions.map(toCapture);
+  }
+  return {
+    types: WORK_ITEM_TYPES2.map((t) => ({ value: t, label: t.charAt(0).toUpperCase() + t.slice(1) })),
+    questions
+  };
+}
+var RECOMMENDED_AGENT = "work-item-agent";
+var RECOMMENDED_SKILL = "work-item-refinement";
+function buildRefinementHandoff(dir, workItemId) {
+  const wi = getWorkItem(dir, workItemId);
+  const config = loadConfig(dir);
+  const projectName = config?.project.name ?? "this project";
+  const mappedModules = loadMappedModules(dir).map((m) => m.id);
+  const multirepo = mappedModules.length > 0;
+  const lines = [
+    `Refine Work Item ${wi.id} \u2014 "${wi.title}" \u2014 in project "${projectName}" using Kaddo.`,
+    "",
+    "Use a Kaddo-enabled agent with access to this repository. Drive the refinement with the",
+    `canonical ${RECOMMENDED_AGENT} and the ${RECOMMENDED_SKILL} skill (via Kaddo MCP or skills).`,
+    "",
+    "Inspect the actual implementation before defining scope \u2014 do not guess affected modules from",
+    "the Work Item title. Read the current behavior in the code first, then classify."
+  ];
+  if (multirepo) {
+    lines.push(
+      "",
+      `This is a multirepo project. Evaluate the scope across all relevant mapped modules (${mappedModules.join(", ")})`,
+      "before finalizing affected_modules and module_coverage."
+    );
+  }
+  const topology = getSystemMapProjection(dir).metadata.topologyStatus;
+  if (topology !== "unavailable") {
+    lines.push(
+      "",
+      `The semantic system Graph is ${topology}. Identify the relevant system entry points, then use`,
+      "the Kaddo Graph (search / neighbors / paths) to find connected components, dependencies, APIs,",
+      "datastores and external systems. Treat Graph-derived entities as IMPACT CANDIDATES, not",
+      "confirmed scope: inspect each candidate in the repository and classify it as affected,",
+      "reviewed-not-affected or unknown, preserving the reason/evidence. A missing Graph edge does not",
+      "mean no impact \u2014 especially when coverage is partial."
+    );
+  } else {
+    lines.push("", "The semantic system Graph is not available yet; refine using the repository and Knowledge.");
+  }
+  lines.push(
+    "",
+    `Update the canonical Work Item ${wi.id} with:`,
+    "- current and target behavior;",
+    "- the end-to-end flow (journey);",
+    "- affected modules;",
+    "- affected system entities (affected_system_entities) and reviewed_system_entities;",
+    "- module coverage;",
+    "- impact analysis across the relevant surfaces;",
+    "- scope confidence and open unknowns;",
+    "- acceptance criteria;",
+    "- relevant Knowledge / ADR relationships.",
+    "",
+    "Do not implement the Work Item. Do not run mutating Git operations."
+  );
+  return {
+    workItemId: wi.id,
+    title: wi.title,
+    projectName,
+    refinement: wi.refinement,
+    recommendedAgent: RECOMMENDED_AGENT,
+    recommendedSkill: RECOMMENDED_SKILL,
+    text: lines.join("\n")
+  };
+}
 export {
   TOPOLOGY_FILE,
+  TopologyWriteError,
   WorkItemNotFoundError,
   WorkItemWriteError,
   analyzeCrossRepoEvidence,
   analyzeScopeCoverage,
+  applyTopologyProposal,
   buildProjectExplanation,
   buildProjectRoute,
   buildReadinessReport,
@@ -9079,7 +9347,10 @@ export {
   discoverKnowledge,
   discoverWorkItems,
   exists,
+  findSystemPaths,
+  getImpactCandidates,
   getSystemMapProjection,
+  getSystemNeighbors,
   getSystemNodeContext,
   getWorkItem,
   getWorkItemCaptureDefinition,
@@ -9096,8 +9367,11 @@ export {
   loadMappedModules,
   loadSystemTopology,
   readFile,
+  searchSystemNodes,
+  topologyRevision,
   transitionWorkItem,
   updateWorkItem,
   validateSystemTopology,
+  validateTopologyProposal,
   validateWorkItem
 };