@kaddo/cli 3.74.1 → 3.76.0

package/dist/core.js

@@ -1625,6 +1625,150 @@ function loadExternalCapsules(dir) {
 }
 
 // src/core/graph.ts
+var KNOWLEDGE2 = "knowledge";
+var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
+var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
+function scopeStatuses(scope) {
+  return scope === "all" ? { included: ALL_STATUSES, excluded: ["archived"] } : { included: ACTIVE_STATUSES, excluded: ["completed", "archived"] };
+}
+function toPosix2(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function slug(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isAdr(a) {
+  return toPosix2(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+}
+function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
+  const scope = opts.scope ?? "active";
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = [];
+  const edgeKeys = /* @__PURE__ */ new Set();
+  const addNode = (node) => {
+    if (!nodes.has(node.id)) nodes.set(node.id, node);
+  };
+  const addEdge = (from, to, type) => {
+    const key = `${from}|${to}|${type}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push({ from, to, type });
+  };
+  const layerDocs = [
+    { id: "business:business", type: "business", label: "Business", files: ["business/business.md"] },
+    { id: "product:product", type: "product", label: "Product", files: ["product/product.md", "product/capabilities.md"] },
+    { id: "tech:tech", type: "tech", label: "Tech", files: ["tech/current-state.md", "tech/codebase.md"] },
+    { id: "delivery:delivery", type: "delivery", label: "Delivery", files: ["delivery/roadmap.md"] }
+  ];
+  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 });
+      presentLayers.push(layer.id);
+    }
+  }
+  for (let i = 0; i < presentLayers.length - 1; i++) {
+    addEdge(presentLayers[i], presentLayers[i + 1], "informs");
+  }
+  const all = discoverKnowledge(dir);
+  const workItems = all.filter((a) => a.isWorkItem);
+  const { included, excluded } = scopeStatuses(scope);
+  const includedSet = new Set(included);
+  const activeWICount = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)).length;
+  const selectedWIs = workItems.filter((a) => a.lifecycle && includedSet.has(a.lifecycle));
+  for (const wi of selectedWIs) {
+    const id = wi.id || wi.title;
+    if (!id || !id.trim()) continue;
+    const wiNodeId = `wi:${id}`;
+    addNode({
+      id: wiNodeId,
+      type: "work-item",
+      label: `${id} ${wi.title}`.trim(),
+      path: wi.relPath,
+      status: wi.lifecycle,
+      knowledge_level: wi.knowledgeLevel || void 0
+    });
+    for (const glob of wi.codeGlobs) {
+      if (!glob || !glob.trim()) continue;
+      const codeId = `code:${glob}`;
+      addNode({ id: codeId, type: "code-glob", label: glob });
+      addEdge(wiNodeId, codeId, "owns");
+    }
+    for (const cap of wi.capabilities) {
+      if (!cap || !cap.trim()) continue;
+      const capId = `capability:${slug(cap) || cap}`;
+      addNode({ id: capId, type: "capability", label: cap });
+      addEdge(wiNodeId, capId, "implements");
+    }
+    for (const dec of wi.decisions) {
+      if (!dec || !dec.trim()) continue;
+      const adrId = `adr:${dec}`;
+      addNode({ id: adrId, type: "decision", label: dec });
+      addEdge(wiNodeId, adrId, "depends_on");
+    }
+    if (wi.initiative) {
+      const initId = `initiative:${slug(wi.initiative) || wi.initiative}`;
+      addNode({ id: initId, type: "initiative", label: wi.initiative });
+      addEdge(wiNodeId, initId, "belongs_to");
+    }
+    if (wi.source === "roadmap" && wi.sourceId) {
+      const candId = `candidate:${wi.sourceId}`;
+      addNode({ id: candId, type: "roadmap-candidate", label: wi.sourceId });
+      addEdge(candId, wiNodeId, "materialized_as");
+    }
+  }
+  for (const adr of all.filter(isAdr)) {
+    const adrLabel = adr.id || adr.title;
+    if (!adrLabel || !adrLabel.trim()) continue;
+    const adrId = `adr:${adrLabel}`;
+    const referenced = nodes.has(adrId);
+    if (scope === "all" || referenced) {
+      nodes.set(adrId, {
+        id: adrId,
+        type: "decision",
+        label: `${adr.id} ${adr.title}`.trim() || adrLabel,
+        path: adr.relPath
+      });
+      for (const glob of adr.codeGlobs) {
+        if (!glob || !glob.trim()) continue;
+        const codeId = `code:${glob}`;
+        addNode({ id: codeId, type: "code-glob", label: glob });
+        addEdge(adrId, codeId, "governs");
+      }
+    }
+  }
+  const capsules = loadExternalRegistry(dir);
+  if (capsules.length > 0) {
+    const projId = `project:${slug(config.project.name) || "project"}`;
+    addNode({ id: projId, type: "project", label: config.project.name });
+    for (const cap of capsules) {
+      const capId = `capsule:${cap.id}`;
+      addNode({ id: capId, type: "knowledge-capsule", label: cap.id, path: cap.path });
+      addEdge(capId, projId, "provides_external_context");
+      for (const wi of selectedWIs) {
+        if (wi.capsules.includes(cap.id)) {
+          addEdge(`wi:${wi.id || wi.title}`, capId, "uses_external_knowledge");
+        }
+      }
+    }
+  }
+  const scopeReason = scope === "all" ? "All supported Work Item statuses are included." : activeWICount === 0 ? "No active Work Items found. Completed Work Items are excluded from active scope." : "Active Work Items only; completed and archived are excluded.";
+  return {
+    generated_at: now.toISOString(),
+    project: {
+      name: config.project.name,
+      state: config.project.state,
+      structure: config.project.structure
+    },
+    scope,
+    scope_reason: scopeReason,
+    included_statuses: included,
+    excluded_statuses: excluded,
+    nodes: [...nodes.values()],
+    edges
+  };
+}
 var ACTIVE_WI_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
 function loadGraphSummary(dir) {
   const p2 = join(dir, ".kaddo", "graph.json");
@@ -1656,6 +1800,161 @@ function loadGraphSummary(dir) {
 }
 
 // src/core/graph-hints.ts
+var KNOWLEDGE3 = "knowledge";
+function toPosix3(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function slug2(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isAdr2(a) {
+  return toPosix3(a.filePath).includes("/tech/decisions/") && Boolean(a.type);
+}
+function capabilityHeadings(dir) {
+  const p2 = join(dir, KNOWLEDGE3, "product", "capabilities.md");
+  if (!exists(p2)) return [];
+  return readFile(p2).split(/\r?\n/).map((l) => l.match(/^#{2,3}\s+(.+?)\s*$/)).filter((m) => Boolean(m)).map((m) => m[1].trim()).filter((h) => !/^(summary|resumen|overview|capabilities|capacidades)$/i.test(h));
+}
+function humanMissing(field) {
+  switch (field) {
+    case "code":
+      return "code ownership";
+    case "capabilities":
+      return "linked capability";
+    case "decisions":
+      return "linked decision";
+    case "source":
+      return "roadmap link";
+    default:
+      return field;
+  }
+}
+function buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
+  const artifacts = discoverKnowledge(dir);
+  const workItems = artifacts.filter((a) => a.isWorkItem);
+  const activeWIs = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle));
+  const adrs = artifacts.filter(isAdr2);
+  const capsules = loadExternalRegistry(dir);
+  const hints = [];
+  const referencedCapabilitySlugs = new Set(
+    workItems.flatMap((w) => w.capabilities.map((c) => slug2(c)))
+  );
+  const referencedCapsuleIds = new Set(workItems.flatMap((w) => w.capsules.map((c) => c)));
+  let activeWithoutCode = 0;
+  let activeWithoutCapabilities = 0;
+  let wisWithoutSource = 0;
+  for (const wi of activeWIs) {
+    const id = wi.id || wi.title;
+    const missing = [];
+    const suggested = {};
+    if (wi.codeGlobs.length === 0) {
+      missing.push("code");
+      suggested.code = ["src/<area>/**"];
+      activeWithoutCode++;
+    }
+    if (wi.capabilities.length === 0) {
+      missing.push("capabilities");
+      suggested.capabilities = ["<capability>"];
+      activeWithoutCapabilities++;
+    }
+    if (wi.decisions.length === 0) {
+      missing.push("decisions");
+      suggested.decisions = ["ADR-XXX"];
+    }
+    const hasSource = Boolean(wi.sourceId) || Boolean(wi.initiative);
+    if (!hasSource) {
+      missing.push("source");
+      wisWithoutSource++;
+    }
+    if (missing.length === 0) continue;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "work-item",
+      path: wi.relPath,
+      severity: "info",
+      missing,
+      reason: "Active Work Item has limited graph relationships.",
+      message: `${id} has no ${missing.map(humanMissing).join(", ")}.`,
+      suggested_front_matter: Object.keys(suggested).length > 0 ? suggested : void 0
+    });
+  }
+  let adrsWithoutCode = 0;
+  for (const adr of adrs) {
+    if (adr.codeGlobs.length > 0) continue;
+    adrsWithoutCode++;
+    const id = adr.id || adr.title;
+    hints.push({
+      artifact_id: id,
+      artifact_type: "decision",
+      path: adr.relPath,
+      severity: "info",
+      missing: ["code"],
+      reason: "This ADR defines technical decisions but does not declare which paths it governs.",
+      message: `${id} has no governed code paths.`,
+      suggested_front_matter: { code: ["<path/to/code>"] }
+    });
+  }
+  for (const cap of capabilityHeadings(dir)) {
+    if (referencedCapabilitySlugs.has(slug2(cap))) continue;
+    hints.push({
+      artifact_id: cap,
+      artifact_type: "capability",
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This capability is declared but no Work Item references it yet.",
+      message: `Capability "${cap}" is not linked to any Work Item.`
+    });
+  }
+  let capsulesWithoutWi = 0;
+  for (const cap of capsules) {
+    if (referencedCapsuleIds.has(cap.id)) continue;
+    capsulesWithoutWi++;
+    hints.push({
+      artifact_id: cap.id,
+      artifact_type: "knowledge-capsule",
+      path: cap.path,
+      severity: "info",
+      missing: ["work-item"],
+      reason: "This Knowledge Capsule is available but no Work Item declares `capsules:` for it.",
+      message: `Knowledge Capsule "${cap.id}" is not linked to any Work Item.`
+    });
+  }
+  const inEdge = /* @__PURE__ */ new Set();
+  for (const e of graph.edges) {
+    inEdge.add(e.from);
+    inEdge.add(e.to);
+  }
+  const nodes = graph.nodes.length;
+  const connected = graph.nodes.filter((n) => inEdge.has(n.id)).length;
+  const relationshipEdges = graph.edges.filter((e) => e.type !== "informs").length;
+  const metrics = {
+    nodes_count: nodes,
+    edges_count: graph.edges.length,
+    connected_nodes_count: connected,
+    isolated_nodes_count: nodes - connected,
+    active_work_items_without_code: activeWithoutCode,
+    active_work_items_without_capabilities: activeWithoutCapabilities,
+    work_items_without_source: wisWithoutSource,
+    adrs_without_code: adrsWithoutCode,
+    capsules_without_related_work_items: capsulesWithoutWi
+  };
+  const quality = assessQuality(nodes, relationshipEdges, hints.length);
+  return {
+    generated_at: now.toISOString(),
+    scope: graph.scope,
+    scope_reason: graph.scope_reason,
+    quality,
+    summary: { nodes, edges: graph.edges.length, hints: hints.length },
+    metrics,
+    hints
+  };
+}
+function assessQuality(nodes, relationshipEdges, hintCount) {
+  if (nodes === 0 || relationshipEdges === 0) return "empty";
+  if (relationshipEdges / nodes < 0.25) return "sparse";
+  if (hintCount > 0) return "partial";
+  return "good";
+}
 function loadGraphHints(dir) {
   const p2 = join(dir, ".kaddo", "graph-hints.json");
   if (!exists(p2)) return null;
@@ -1708,7 +2007,7 @@ function skillGroupCounts(skills) {
 }
 
 // src/core/knowledge-discovery.ts
-var KNOWLEDGE2 = "knowledge";
+var KNOWLEDGE4 = "knowledge";
 var CONSOLIDATED_TYPE = {
   Business: "business",
   Product: "product",
@@ -1750,10 +2049,10 @@ function layerForType(type) {
 }
 function layerFromPath(filePath) {
   const p2 = filePath.replace(/\\/g, "/");
-  if (p2.includes(`/${KNOWLEDGE2}/business/`)) return "Business";
-  if (p2.includes(`/${KNOWLEDGE2}/product/`)) return "Product";
-  if (p2.includes(`/${KNOWLEDGE2}/tech/`)) return "Tech";
-  if (p2.includes(`/${KNOWLEDGE2}/delivery/`)) return "Delivery";
+  if (p2.includes(`/${KNOWLEDGE4}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE4}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE4}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE4}/delivery/`)) return "Delivery";
   return null;
 }
 function basename(p2) {
@@ -1766,7 +2065,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE2);
+  const archDir = join(dir, KNOWLEDGE4);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -1788,7 +2087,7 @@ function discoverLayers(dir) {
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE2, "tech", "decisions"))) acc.Tech.structured = true;
+  if (existsDirWithMd(join(dir, KNOWLEDGE4, "tech", "decisions"))) acc.Tech.structured = true;
   return ["Business", "Product", "Tech", "Delivery"].map((layer) => ({
     layer,
     status: statusFor(layer, acc[layer]),
@@ -3686,9 +3985,6 @@ var RECOMMENDED_SKILLS = [...SKILL_GROUPS.delivery, ...SKILL_GROUPS.tech];
 function skillInstallPath(id) {
   return `knowledge/skills/${id}/skill.md`;
 }
-function skillById(id) {
-  return SKILLS.find((s) => s.id === id);
-}
 
 // src/agents/responsibility.ts
 var RESPONSIBILITY_MATRIX = {
@@ -7456,6 +7752,17 @@ function analyzeCrossRepoEvidence(input) {
 
 // src/core/work-items.ts
 import matter6 from "gray-matter";
+function computeRefinementStatus(wi) {
+  const aspects = {
+    outcome: Boolean(wi.currentBehavior?.trim() || wi.targetBehavior?.trim()),
+    journey: Boolean(wi.entryPoints?.trim() || wi.endToEndFlow?.trim()),
+    modules: wi.affectedModules.length > 0 || wi.moduleCoverage.length > 0,
+    impact: wi.impactAnalysis.length > 0,
+    acceptance: wi.acceptanceCriteria.length > 0
+  };
+  const refined = aspects.outcome && aspects.modules && aspects.acceptance;
+  return { status: refined ? "refined" : "needs-refinement", aspects };
+}
 var WorkItemNotFoundError = class extends Error {
   constructor(workItemId) {
     super(`Work Item "${workItemId}" was not found.`);
@@ -7531,8 +7838,9 @@ function getWorkItem(dir, workItemId) {
   const fm = match.rawFrontmatter;
   const knowledge = discoverKnowledge(dir).filter((a) => !a.isWorkItem);
   const knowledgeById = new Map(knowledge.filter((k) => k.id).map((k) => [k.id, k]));
-  return {
+  const detail = {
     ...base,
+    summary: match.summary?.trim() || null,
     actor: sectionText(sections, ["actor"]),
     outcome: sectionText(sections, ["actor and outcome", "outcome", "expected result"]),
     currentBehavior: sectionText(sections, ["current behavior", "current behaviour"]),
@@ -7552,6 +7860,7 @@ function getWorkItem(dir, workItemId) {
     source: parseWorkItemSource(fm),
     path: match.relPath
   };
+  return { ...detail, refinement: computeRefinementStatus(detail) };
 }
 function readBody(filePath) {
   try {
@@ -8354,140 +8663,154 @@ function getWorkItemCaptureDefinition() {
     questions
   };
 }
-function getWorkItemAgentAssets() {
-  const agent = AGENT_PROMPTS.find((p2) => p2.fileName === "work-item-agent.md");
-  const skill2 = skillById("work-item-refinement");
-  return { agentPrompt: agent?.content ?? "", skill: skill2?.content ?? null };
-}
-function assembleRefinementContext(dir, workItemId) {
-  const edit = getWorkItemForEdit(dir, workItemId);
+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 knowledgeArtifacts = discoverKnowledge(dir).filter(
-    (a) => !a.isWorkItem && a.type !== "skill" && a.type !== "agent" && a.layer !== "unknown"
+  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."
   );
-  const decisions = knowledgeArtifacts.filter((a) => a.type === "adr" || /^adr-/i.test(a.id)).map((a) => ({ id: a.id, title: a.title || a.id }));
-  const knowledge = knowledgeArtifacts.filter((a) => !(a.type === "adr" || /^adr-/i.test(a.id))).map((a) => ({ id: a.id || a.relPath, title: a.title || a.id, layer: a.layer, type: a.type || void 0, summary: a.summary || void 0 }));
-  const modules = ["core", ...loadMappedModules(dir).map((m) => m.id)].filter((v, i, arr) => arr.indexOf(v) === i);
   return {
-    workItem: { id: edit.id, title: edit.title, status: edit.status, intent: edit.summary ?? edit.title, current: stripEdit(edit) },
-    project: { name: config?.project.name ?? "unknown", state: config?.project.state ?? "unknown", structure: config?.project.structure ?? "unknown" },
-    modules,
-    knowledge,
-    decisions,
-    revision: edit.revision
+    workItemId: wi.id,
+    title: wi.title,
+    projectName,
+    refinement: wi.refinement,
+    recommendedAgent: RECOMMENDED_AGENT,
+    recommendedSkill: RECOMMENDED_SKILL,
+    text: lines.join("\n")
   };
 }
-function stripEdit(edit) {
-  const { id: _i, status: _s, revision: _r, path: _p, editable: _e, editableReason: _er, ...input } = edit;
-  return input;
-}
-var VALID_COVERAGE2 = /* @__PURE__ */ new Set(["affected", "reviewed-not-affected", "unknown", "not-applicable"]);
-var VALID_CONFIDENCE2 = /* @__PURE__ */ new Set(["high", "medium", "low"]);
-function str(v) {
-  return typeof v === "string" && v.trim() ? v.trim() : void 0;
-}
-function strList(v) {
-  return Array.isArray(v) ? v.map((x) => typeof x === "string" ? x.trim() : "").filter(Boolean) : [];
-}
-function normalizeAndValidateProposal(dir, workItemId, proposal) {
-  const ctx = assembleRefinementContext(dir, workItemId);
-  const knownModules = new Set(ctx.modules);
-  const knownDecisions = new Set(ctx.decisions.map((d) => d.id));
-  const knownKnowledge = new Set(ctx.knowledge.map((k) => k.id));
-  const extraFindings = [];
-  const input = { ...ctx.workItem.current };
-  if (str(proposal.title)) input.title = str(proposal.title);
-  const o = proposal.outcome ?? {};
-  if (str(o.actor) !== void 0) input.actor = str(o.actor);
-  if (str(o.observableOutcome) !== void 0) input.outcome = str(o.observableOutcome);
-  if (str(o.currentBehavior) !== void 0) input.currentBehavior = str(o.currentBehavior);
-  if (str(o.targetBehavior) !== void 0) input.targetBehavior = str(o.targetBehavior);
-  const j = proposal.journey ?? {};
-  if (j.entryPoints) input.entryPoints = strList(j.entryPoints).join("\n");
-  if (j.flow) input.endToEndFlow = strList(j.flow).map((s) => `- ${s}`).join("\n");
-  if (proposal.moduleCoverage) {
-    input.moduleCoverage = proposal.moduleCoverage.filter((c) => {
-      if (!knownModules.has(c.id)) {
-        extraFindings.push({ level: "warning", message: `Proposed module "${c.id}" is not registered and was not included.` });
-        return false;
-      }
-      return VALID_COVERAGE2.has(c.status);
-    }).map((c) => ({ id: c.id, status: c.status, ...str(c.reason) ? { reason: str(c.reason) } : {} }));
-  }
-  const affected = /* @__PURE__ */ new Set();
-  for (const m of proposal.affectedModules ?? []) if (knownModules.has(m)) affected.add(m);
-  for (const c of input.moduleCoverage) if (c.status === "affected") affected.add(c.id);
-  if (proposal.affectedModules || proposal.moduleCoverage) input.affectedModules = [...affected];
-  if (proposal.impactAnalysis) {
-    input.impactAnalysis = proposal.impactAnalysis.filter((s) => VALID_COVERAGE2.has(s.status) && str(s.surface)).map((s) => ({ surface: str(s.surface), status: s.status, ...str(s.reason) ? { reason: str(s.reason) } : {}, ...str(s.question) ? { question: str(s.question) } : {} }));
-  }
-  if (proposal.scopeConfidence && VALID_CONFIDENCE2.has(proposal.scopeConfidence.level)) {
-    input.scopeConfidence = { level: proposal.scopeConfidence.level, reasons: strList(proposal.scopeConfidence.reasons) };
-  }
-  if (proposal.scopeUnknowns) input.scopeUnknowns = strList(proposal.scopeUnknowns);
-  if (proposal.acceptanceCriteria) input.acceptanceCriteria = strList(proposal.acceptanceCriteria).map((t) => ({ text: t, checked: null }));
-  if (proposal.linkedDecisions) {
-    input.decisions = proposal.linkedDecisions.filter((id) => {
-      if (!knownDecisions.has(id)) {
-        extraFindings.push({ level: "warning", message: `Proposed decision "${id}" does not exist and was not linked.` });
-        return false;
-      }
-      return true;
-    });
-  }
-  if (proposal.relatedKnowledge) {
-    input.relatedKnowledge = proposal.relatedKnowledge.filter((id) => {
-      if (!knownKnowledge.has(id)) {
-        extraFindings.push({ level: "warning", message: `Proposed knowledge "${id}" could not be resolved and was not linked.` });
-        return false;
-      }
-      return true;
-    });
-  }
-  const findings = [...extraFindings, ...evaluate(input, knownModules)];
-  const blocking = findings.filter((f) => f.level === "blocking").length;
-  const warning = findings.filter((f) => f.level === "warning").length;
-  const fyi = findings.filter((f) => f.level === "fyi").length;
-  return { input, validation: { findings, blocking, warning, fyi, canApply: true } };
+
+// src/core/system-map.ts
+var EDGE_LABELS = {
+  informs: "informs",
+  belongs_to: "belongs to",
+  materialized_as: "materialized as",
+  owns: "owns",
+  implements: "implements",
+  depends_on: "depends on",
+  governs: "governs",
+  provides_external_context: "provides external context",
+  uses_external_knowledge: "uses external knowledge"
+};
+function emptyProjection(name, structure) {
+  return {
+    system: { name },
+    nodes: [],
+    relationships: [],
+    groups: [],
+    metadata: { projectName: name, structure, nodeCount: 0, relationshipCount: 0, coverage: "empty", available: false }
+  };
 }
-function evaluate(input, knownModules) {
-  const findings = [];
-  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.` });
+function getSystemMapProjection(dir) {
+  const config = loadConfig(dir);
+  if (!config) return emptyProjection("unknown", "unknown");
+  const graph = buildGraph(dir, config, { scope: "all" });
+  const hints = buildGraphHints(dir, graph);
+  const knowledgeByPath = /* @__PURE__ */ new Map();
+  for (const a of discoverKnowledge(dir).filter((a2) => !a2.isWorkItem)) {
+    const id = a.id || a.relPath.replace(/[/\\]/g, "-").replace(/\.md$/, "");
+    const layer = a.layer === "module" ? "tech" : a.layer;
+    knowledgeByPath.set(a.relPath, { id, layer });
+  }
+  const wiModules = /* @__PURE__ */ new Map();
+  for (const wi of discoverWorkItems(dir)) wiModules.set(wi.id || wi.title, wi.affectedModules);
+  const mapped = loadMappedModules(dir);
+  const groupIds = /* @__PURE__ */ new Set(["core", ...mapped.map((m) => m.id)]);
+  const nodes = graph.nodes.map((n) => toNode(n, knowledgeByPath, wiModules, groupIds));
+  const relationships = graph.edges.map((e) => ({
+    id: `${e.from}~${e.type}~${e.to}`,
+    source: e.from,
+    target: e.to,
+    type: e.type,
+    label: EDGE_LABELS[e.type] ?? e.type.replace(/_/g, " ")
+  }));
+  const usedGroups = new Set(nodes.map((n) => n.moduleId).filter(Boolean));
+  const allGroups = [
+    { id: "core", label: "core", repositoryId: "core", available: true },
+    // A mapped module is available when its repository path resolves relative to the project.
+    ...mapped.map((m) => ({ id: m.id, label: m.id, repositoryId: m.id, available: m.repoPath ? exists(join(dir, m.repoPath)) : false }))
+  ];
+  const groups = allGroups.filter((g) => usedGroups.has(g.id) || g.available === false);
+  return {
+    system: { name: config.project.name },
+    nodes,
+    relationships,
+    groups,
+    metadata: {
+      projectName: config.project.name,
+      structure: config.project.structure,
+      nodeCount: nodes.length,
+      relationshipCount: relationships.length,
+      coverage: hints.quality,
+      available: nodes.length > 0
     }
+  };
+}
+function toNode(n, knowledgeByPath, wiModules, groupIds) {
+  const node = { id: n.id, type: n.type, label: n.label };
+  if (n.status) node.status = n.status;
+  if (n.path && !/^([a-zA-Z]:[\\/]|\/)/.test(n.path)) node.path = n.path;
+  if (n.type === "work-item") {
+    const wiId = n.id.startsWith("wi:") ? n.id.slice(3) : n.id;
+    node.workItemRef = wiId;
+    const affected = (wiModules.get(wiId) ?? []).filter((m) => groupIds.has(m));
+    if (affected.length === 1) node.moduleId = affected[0];
   }
-  for (const m of input.affectedModules) {
-    if (!knownModules.has(m)) findings.push({ level: "blocking", message: `Module "${m}" is not registered in this project.` });
+  if (n.path) {
+    const ref = knowledgeByPath.get(n.path);
+    if (ref) node.knowledgeRef = ref;
   }
-  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 s of input.impactAnalysis) if (s.status === "unknown") findings.push({ level: "fyi", message: `Impact on ${s.surface} is unknown.` });
-  return findings;
-}
-function applyRefinement(dir, workItemId, proposal, expectedRevision) {
-  const { input } = normalizeAndValidateProposal(dir, workItemId, proposal);
-  return updateWorkItem(dir, workItemId, input, expectedRevision);
+  return node;
 }
 export {
   WorkItemNotFoundError,
   WorkItemWriteError,
   analyzeCrossRepoEvidence,
   analyzeScopeCoverage,
-  applyRefinement,
-  assembleRefinementContext,
   buildProjectExplanation,
   buildProjectRoute,
   buildReadinessReport,
+  buildRefinementHandoff,
+  computeRefinementStatus,
   createWorkItem,
   cwd,
   discoverKnowledge,
   discoverWorkItems,
   exists,
+  getSystemMapProjection,
   getWorkItem,
-  getWorkItemAgentAssets,
   getWorkItemCaptureDefinition,
   getWorkItemForEdit,
   getWorkItems,
@@ -8500,7 +8823,6 @@ export {
   lifecycleStateOf,
   loadConfig,
   loadMappedModules,
-  normalizeAndValidateProposal,
   readFile,
   transitionWorkItem,
   updateWorkItem,

package/package.json

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