@kaddo/cli 3.79.0 → 3.81.0

package/dist/core.js

@@ -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,51 @@ 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 parseGraphReason(v) {
+  if (!v || typeof v !== "object") return null;
+  const o = v;
+  const relationship = typeof o.relationship === "string" && o.relationship.trim() ? o.relationship.trim() : null;
+  const path4 = Array.isArray(o.path) ? o.path.map(String).filter(Boolean) : [];
+  return relationship || path4.length ? { relationship, path: path4 } : null;
+}
+function parseExplain(o) {
+  const refs = Array.isArray(o.evidence) ? o.evidence : Array.isArray(o.evidence_refs) ? o.evidence_refs : [];
+  return {
+    reason: typeof o.reason === "string" && o.reason.trim() ? o.reason.trim() : null,
+    graphReason: parseGraphReason(o.graph_reason),
+    evidenceRefs: refs.map(String).filter(Boolean),
+    evidenceSummary: typeof o.evidence_summary === "string" && o.evidence_summary.trim() ? o.evidence_summary.trim() : null
+  };
+}
+function emptyExplain() {
+  return { reason: null, graphReason: null, evidenceRefs: [], evidenceSummary: null };
+}
+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((raw) => {
+    if (typeof raw === "string") return raw ? { ...resolve(raw), ...emptyExplain() } : null;
+    if (raw && typeof raw === "object") {
+      const o = raw;
+      const id = String(o.id ?? "");
+      return id ? { ...resolve(id), ...parseExplain(o) } : null;
+    }
+    return null;
+  }).filter((e) => e != null) : [];
+  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 ?? "")), ...parseExplain(r), status: String(r.status ?? "unknown") })).filter((r) => r.id) : [];
+  const graphRevision = typeof fm.graph_revision === "string" && fm.graph_revision.trim() ? fm.graph_revision.trim() : null;
+  const graphCoverage = topology.entities.length === 0 ? "unavailable" : topology.relationships.length > 0 ? "available" : "partial";
+  return { affectedSystemEntities: affected, reviewedSystemEntities: reviewed, graphRevision, graphCoverage };
+}
 function readBody(filePath) {
   try {
     const raw = readFile(filePath);
@@ -8029,9 +8329,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 +8534,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 +8544,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 +8557,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 +8865,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 +8887,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) {
@@ -8599,374 +8899,75 @@ function validateWorkItem(dir, id) {
   const modules = validModuleIds(dir);
   for (const c of input.moduleCoverage) {
     if (c.status === "affected" && !input.affectedModules.includes(c.id)) {
-      findings.push({ level: "blocking", message: `${c.id} is marked affected in module coverage but is missing from affected_modules.` });
-    }
-  }
-  for (const m of input.affectedModules) {
-    if (!modules.has(m)) findings.push({ level: "blocking", message: `Module "${m}" is not registered in this project.` });
-  }
-  if (!input.targetBehavior?.trim()) findings.push({ level: "warning", message: "Target behavior is not defined." });
-  if (input.acceptanceCriteria.length === 0) findings.push({ level: "warning", message: "No acceptance criteria have been defined." });
-  if (input.scopeConfidence?.level === "low") findings.push({ level: "warning", message: "Scope confidence is Low." });
-  if (!input.scopeConfidence) findings.push({ level: "warning", message: "Scope confidence has not been assessed." });
-  for (const c of input.moduleCoverage) {
-    if (c.status === "reviewed-not-affected") findings.push({ level: "fyi", message: `${c.id} was reviewed and is not affected.` });
-  }
-  for (const s of input.impactAnalysis) {
-    if (s.status === "unknown") findings.push({ level: "fyi", message: `Impact on ${s.surface} is unknown.` });
-  }
-  const canMarkReady = !findings.some((f) => f.level === "blocking");
-  return { findings, canMarkReady };
-}
-var ALLOWED = { draft: ["ready"], ready: ["draft"] };
-function transitionWorkItem(dir, id, to, expectedRevision) {
-  const { filePath } = findArtifact(dir, id);
-  const raw = readFile(filePath);
-  if (revisionOf(raw) !== expectedRevision) {
-    throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
-  }
-  const { data, content } = matter7(raw);
-  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
-  if (!(ALLOWED[from] ?? []).includes(to)) {
-    throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
-  }
-  if (to === "ready") {
-    const { canMarkReady } = validateWorkItem(dir, id);
-    if (!canMarkReady) throw new WorkItemWriteError("INVALID_TRANSITION", "This Work Item has blocking issues and cannot be marked Ready.");
-  }
-  const nextData = { ...data, status: to };
-  const nextRaw = serialize(nextData, content);
-  const filename = path2.basename(filePath);
-  const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
-  const targetPath = join(dir, targetRel);
-  atomicWrite(targetPath, nextRaw);
-  if (path2.resolve(targetPath) !== path2.resolve(filePath)) {
-    try {
-      fs2.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, stringify as stringifyYaml4 } from "yaml";
-import fs3 from "fs";
-import path3 from "path";
-import crypto2 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;
+      findings.push({ level: "blocking", message: `${c.id} is marked affected in module coverage but is missing from affected_modules.` });
     }
-    if (!entityIds.has(from) || !entityIds.has(to)) {
-      findings.push({ level: "blocking", message: `Relationship ${from} \u2192 ${to} references an unknown entity endpoint.` });
+  }
+  for (const m of input.affectedModules) {
+    if (!modules.has(m)) findings.push({ level: "blocking", message: `Module "${m}" is not registered in this project.` });
+  }
+  if (!input.targetBehavior?.trim()) findings.push({ level: "warning", message: "Target behavior is not defined." });
+  if (input.acceptanceCriteria.length === 0) findings.push({ level: "warning", message: "No acceptance criteria have been defined." });
+  if (input.scopeConfidence?.level === "low") findings.push({ level: "warning", message: "Scope confidence is Low." });
+  if (!input.scopeConfidence) findings.push({ level: "warning", message: "Scope confidence has not been assessed." });
+  for (const c of input.moduleCoverage) {
+    if (c.status === "reviewed-not-affected") findings.push({ level: "fyi", message: `${c.id} was reviewed and is not affected.` });
+  }
+  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 idOf = (raw2) => typeof raw2 === "string" ? raw2 : raw2 && typeof raw2 === "object" ? String(raw2.id ?? "") : "";
+  const affectedEntities = Array.isArray(fm.affected_system_entities) ? fm.affected_system_entities.map(idOf).filter(Boolean) : [];
+  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;
     }
-    const key = `${from}~${type}~${to}`;
-    if (seenRels.has(key)) {
-      findings.push({ level: "warning", message: `Duplicate relationship ${from} ${type} ${to} was skipped.` });
-      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.` });
     }
-    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 crypto2.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 atomicWrite2(filePath, content) {
-  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
-  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  fs3.writeFileSync(tmp, content, "utf-8");
-  try {
-    fs3.renameSync(tmp, filePath);
-  } catch (err) {
-    try {
-      fs3.rmSync(tmp, { force: true });
-    } catch {
+  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.` });
     }
-    throw err;
   }
+  const canMarkReady = !findings.some((f) => f.level === "blocking");
+  return { findings, canMarkReady };
 }
-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.");
+var ALLOWED = { draft: ["ready"], ready: ["draft"] };
+function transitionWorkItem(dir, id, to, expectedRevision) {
+  const { filePath } = findArtifact(dir, id);
+  const raw = readFile(filePath);
+  if (revisionOf(raw) !== expectedRevision) {
+    throw new WorkItemWriteError("WORK_ITEM_CONFLICT", "This Work Item changed outside Kaddo Admin. Reload the latest version before continuing.");
   }
-  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 { data, content } = matter7(raw);
+  const from = lifecycleStateOf({ status: String(data.status ?? ""), filePath });
+  if (!(ALLOWED[from] ?? []).includes(to)) {
+    throw new WorkItemWriteError("INVALID_TRANSITION", `Cannot transition a ${from} Work Item to ${to}.`);
   }
-  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);
+  if (to === "ready") {
+    const { canMarkReady } = validateWorkItem(dir, id);
+    if (!canMarkReady) throw new WorkItemWriteError("INVALID_TRANSITION", "This Work Item has blocking issues and cannot be marked Ready.");
   }
-  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.");
-  atomicWrite2(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.`);
+  const nextData = { ...data, status: to };
+  const nextRaw = serialize(nextData, content);
+  const filename = path3.basename(filePath);
+  const targetRel = `${WORK_ITEMS_DIR}/${to}/${filename}`;
+  const targetPath = join(dir, targetRel);
+  atomicWrite2(targetPath, nextRaw);
+  if (path3.resolve(targetPath) !== path3.resolve(filePath)) {
+    try {
+      fs3.rmSync(filePath, { force: true });
+    } catch {
+    }
   }
-  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")
-  };
+  return { revision: revisionOf(nextRaw), status: to, path: targetRel };
 }
 
 // src/core/system-map.ts
@@ -9150,6 +9151,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;
@@ -9166,6 +9279,93 @@ 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 the canonical ${RECOMMENDED_AGENT} and the ${RECOMMENDED_SKILL} skill (via Kaddo MCP or skills),`,
+    "with access to this repository.",
+    "",
+    "Inspect the actual implementation and the relevant mapped modules before defining the final 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}. When semantic system topology is available:`,
+      "1. identify the relevant system entry points;",
+      "2. query the Kaddo Graph (search / neighbors / paths) for connected entities;",
+      "3. treat Graph results as IMPACT CANDIDATES, not confirmed scope;",
+      "4. inspect the actual implementation in the repository for each relevant candidate;",
+      "5. classify each candidate as affected, reviewed-not-affected or unknown;",
+      "6. preserve the evidence and reasons behind each classification.",
+      "",
+      "A missing Graph relationship does not mean no impact, especially when Graph coverage is partial \u2014",
+      "keep inspecting the repository beyond the Graph candidates when the task requires it."
+    );
+  } else {
+    lines.push(
+      "",
+      "The semantic system Graph is unavailable. Continue repository-driven refinement normally, using the",
+      "repository, Knowledge and mapped modules \u2014 the Graph is enrichment, not a prerequisite."
+    );
+  }
+  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,
@@ -9185,7 +9385,10 @@ export {
   discoverKnowledge,
   discoverWorkItems,
   exists,
+  findSystemPaths,
+  getImpactCandidates,
   getSystemMapProjection,
+  getSystemNeighbors,
   getSystemNodeContext,
   getWorkItem,
   getWorkItemCaptureDefinition,
@@ -9202,6 +9405,7 @@ export {
   loadMappedModules,
   loadSystemTopology,
   readFile,
+  searchSystemNodes,
   topologyRevision,
   transitionWorkItem,
   updateWorkItem,