@kaddo/cli 3.9.0 → 3.10.0

package/dist/index.js

@@ -4044,9 +4044,11 @@ function parseArtifact(filePath, raw) {
       knowledgeLevel: String(data.knowledge_level ?? ""),
       codeGlobs: globs,
       domains: Array.isArray(data.domains) ? data.domains : [],
+      capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String).filter(Boolean) : [],
       status: String(data.status ?? ""),
       phase: String(data.phase ?? ""),
-      initiative: String(data.initiative ?? data.source_initiative ?? "")
+      initiative: String(data.initiative ?? data.source_initiative ?? ""),
+      source: data.source ? String(data.source) : ""
     };
   } catch {
     return null;
@@ -4071,6 +4073,94 @@ function readArtifacts(archDir) {
   return artifacts;
 }
 
+// src/core/lifecycle.ts
+var LIFECYCLE_STATES = [
+  "draft",
+  "ready",
+  "in-progress",
+  "blocked",
+  "completed",
+  "archived"
+];
+var ACTIVE_STATES = ["draft", "ready", "in-progress", "blocked"];
+var LEGACY_STATUS_MAP = {
+  done: "completed",
+  cancelled: "archived",
+  canceled: "archived",
+  "in-progress": "in-progress"
+};
+var STATE_SET = new Set(LIFECYCLE_STATES);
+function isLifecycleState(s) {
+  return STATE_SET.has(s);
+}
+function isActiveState(s) {
+  return ACTIVE_STATES.includes(s);
+}
+function lifecycleFolderOf(filePath) {
+  const p2 = filePath.replace(/\\/g, "/");
+  const m = p2.match(/\/delivery\/work-items\/([^/]+)\//);
+  if (m && isLifecycleState(m[1])) return m[1];
+  return null;
+}
+function lifecycleStateOf(item) {
+  const status = (item.status ?? "").trim().toLowerCase();
+  if (isLifecycleState(status)) return status;
+  if (status && LEGACY_STATUS_MAP[status]) return LEGACY_STATUS_MAP[status];
+  const folder = lifecycleFolderOf(item.filePath ?? "");
+  if (folder) return folder;
+  return "ready";
+}
+function emptyLifecycleCounts() {
+  return Object.fromEntries(LIFECYCLE_STATES.map((s) => [s, 0]));
+}
+function lifecycleCounts(states) {
+  const counts = emptyLifecycleCounts();
+  for (const s of states) counts[s]++;
+  return counts;
+}
+
+// src/services/knowledge-artifacts.ts
+var ARCH_DIR2 = "knowledge";
+function toPosix(p2) {
+  return p2.replace(/\\/g, "/");
+}
+function relativeTo(dir, filePath) {
+  const base = toPosix(dir).replace(/\/+$/, "");
+  const full = toPosix(filePath);
+  return full.startsWith(base + "/") ? full.slice(base.length + 1) : full;
+}
+function isWorkItemArtifact(a) {
+  return toPosix(a.filePath).includes("/delivery/work-items/") && Boolean(a.type);
+}
+function classifyLayer(posixPath) {
+  if (posixPath.includes("/knowledge/business/")) return "business";
+  if (posixPath.includes("/knowledge/product/")) return "product";
+  if (posixPath.includes("/knowledge/tech/modules/") || posixPath.includes("/knowledge/modules/"))
+    return "module";
+  if (posixPath.includes("/knowledge/tech/")) return "tech";
+  if (posixPath.includes("/knowledge/delivery/")) return "delivery";
+  return "unknown";
+}
+function enrich(dir, a) {
+  const posix = toPosix(a.filePath);
+  const isWi = isWorkItemArtifact(a);
+  return {
+    ...a,
+    relPath: relativeTo(dir, a.filePath),
+    layer: classifyLayer(posix),
+    isWorkItem: isWi,
+    lifecycle: isWi ? lifecycleStateOf({ status: a.status, filePath: a.filePath }) : void 0
+  };
+}
+function discoverKnowledge(dir) {
+  const archDir = join(dir, ARCH_DIR2);
+  if (!exists(archDir)) return [];
+  return readArtifacts(archDir).map((a) => enrich(dir, a));
+}
+function discoverWorkItems(dir) {
+  return discoverKnowledge(dir).filter((a) => a.isWorkItem);
+}
+
 // src/core/diff-analysis.ts
 import { minimatch } from "minimatch";
 function normalizePath(p2) {
@@ -4463,7 +4553,7 @@ function collectMatchedDomains(matchedArtifactDomains) {
 }
 
 // src/commands/guard.ts
-var ARCH_DIR2 = "knowledge";
+var ARCH_DIR3 = "knowledge";
 var CONFIG_PATH2 = ".kaddo/config.yml";
 function loadConfig2(dir) {
   const configPath = join(dir, CONFIG_PATH2);
@@ -4607,12 +4697,12 @@ async function runGuard(opts = {}) {
     console.log("kaddo guard: no modified files detected.");
     return;
   }
-  const archDir = join(dir, ARCH_DIR2);
+  const archDir = join(dir, ARCH_DIR3);
   if (!exists(archDir)) {
     console.log("kaddo guard: no knowledge/ directory found. Run `kaddo init` first.");
     return;
   }
-  const artifacts = readArtifacts(archDir);
+  const artifacts = discoverKnowledge(dir);
   const result = analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership);
   const pluginSignals = runPlugins(plugins, currentFiles, (filePath) => {
     const abs = join(dir, filePath);
@@ -4724,6 +4814,110 @@ function runIgnoreRemove(artifactId) {
 import matter2 from "gray-matter";
 import { parse as parseYaml8 } from "yaml";
 
+// src/core/delivery-phase.ts
+function layer(layers, name) {
+  return layers.find((l) => l.layer === name)?.status ?? "Missing";
+}
+function baseComplete(layers) {
+  return layer(layers, "Business") !== "Missing" && layer(layers, "Product") !== "Missing" && layer(layers, "Tech") !== "Missing";
+}
+function determinePhase(input) {
+  const { roadmap, workItems } = input;
+  const active = workItems.byState.draft + workItems.byState.ready + workItems.byState["in-progress"] + workItems.byState.blocked;
+  if (!baseComplete(input.layers)) return "Discovery";
+  if (!roadmap.present) return "Planning";
+  if (workItems.total === 0) return "Delivery Preparation";
+  if (active > 0) return "Active Delivery";
+  return "Maintenance";
+}
+function ownershipPct(o) {
+  if (o.workItemsTotal === 0) return 100;
+  return Math.round(o.workItemsWithOwnership / o.workItemsTotal * 100);
+}
+function buildReasons(input) {
+  const reasons = [];
+  reasons.push(input.roadmap.present ? "Roadmap available" : "No roadmap yet");
+  if (input.roadmap.present) {
+    reasons.push(`${input.roadmap.materialized} materialized work item(s)`);
+    if (input.roadmap.remaining > 0) reasons.push(`${input.roadmap.remaining} roadmap candidate(s) remaining`);
+  }
+  const active = LIFECYCLE_STATES.filter((s) => input.workItems.byState[s] > 0 && s !== "completed" && s !== "archived");
+  if (active.length > 0) {
+    reasons.push(active.map((s) => `${s}: ${input.workItems.byState[s]}`).join(", "));
+  }
+  if (input.workItems.total > 0) reasons.push(`Ownership coverage ${ownershipPct(input.ownership)}%`);
+  return reasons;
+}
+function firstMissingLayerAgent(layers) {
+  if (layer(layers, "Business") === "Missing")
+    return { agent: "business-agent", step: "Use business-agent to create knowledge/business/business.md" };
+  if (layer(layers, "Product") === "Missing")
+    return { agent: "capability-agent", step: "Use capability-agent to create knowledge/product/capabilities.md" };
+  return { agent: "architecture-agent", step: "Use architecture-agent to create knowledge/tech/current-state.md" };
+}
+function assessPhase(input) {
+  const phase = determinePhase(input);
+  const reasons = buildReasons(input);
+  const bs = input.workItems.byState;
+  const items = input.workItems.items;
+  const firstOf = (s) => items.find((i) => i.lifecycle === s);
+  let recommendedAgents2 = [];
+  let nextStep = "";
+  switch (phase) {
+    case "Discovery": {
+      const m = firstMissingLayerAgent(input.layers);
+      recommendedAgents2 = [m.agent];
+      nextStep = m.step;
+      break;
+    }
+    case "Planning": {
+      recommendedAgents2 = ["roadmap-agent"];
+      nextStep = "Use roadmap-agent to create knowledge/delivery/roadmap.md";
+      break;
+    }
+    case "Delivery Preparation": {
+      recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
+      const n = input.roadmap.remaining || input.roadmap.candidates;
+      nextStep = `Run \`kaddo create --from roadmap\`${n ? ` (${n} candidate(s))` : ""}, then refine with work-item-agent`;
+      break;
+    }
+    case "Active Delivery": {
+      if (bs.ready > 0) {
+        const wi = firstOf("ready");
+        recommendedAgents2 = ["implementation-agent"];
+        nextStep = wi ? `Start ${wi.id} \u2014 ${wi.title} (ready \u2192 in-progress)` : "Start a ready Work Item";
+      } else if (bs["in-progress"] > 0) {
+        const wi = firstOf("in-progress");
+        recommendedAgents2 = ["implementation-agent", "kaddo scan", "kaddo owners suggest", "kaddo guard"];
+        nextStep = wi ? `Continue ${wi.id} \u2014 ${wi.title}; then run kaddo scan, owners suggest, guard` : "Continue the in-progress Work Item; then scan, owners suggest, guard";
+      } else if (bs.draft > 0) {
+        const wi = firstOf("draft");
+        recommendedAgents2 = ["work-item-agent"];
+        nextStep = wi ? `Refine ${wi.id} from draft to ready` : "Refine a draft Work Item to ready";
+      } else if (bs.blocked > 0) {
+        const wi = firstOf("blocked");
+        recommendedAgents2 = ["work-item-agent"];
+        nextStep = wi ? `Resolve the blocker on ${wi.id} \u2014 ${wi.title}` : "Resolve the blockers on active work";
+      }
+      if (input.ownership.workItemsMissingOwnership > 0) {
+        recommendedAgents2.push("kaddo owners suggest");
+      }
+      break;
+    }
+    case "Maintenance": {
+      if (input.roadmap.remaining > 0) {
+        recommendedAgents2 = ["kaddo create --from roadmap", "work-item-agent"];
+        nextStep = `Materialize ${input.roadmap.remaining} remaining roadmap candidate(s)`;
+      } else {
+        recommendedAgents2 = ["roadmap-agent"];
+        nextStep = "No active work \u2014 use roadmap-agent to plan the next initiative";
+      }
+      break;
+    }
+  }
+  return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep };
+}
+
 // src/core/knowledge-discovery.ts
 var KNOWLEDGE = "knowledge";
 var CONSOLIDATED_TYPE = {
@@ -4787,29 +4981,29 @@ function discoverLayers(dir) {
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
-    const layer = layerForType(type) ?? layerFromPath(a.filePath);
-    if (!layer) continue;
-    const slot = acc[layer];
+    const layer2 = layerForType(type) ?? layerFromPath(a.filePath);
+    if (!layer2) continue;
+    const slot = acc[layer2];
     slot.detected.add(basename(a.filePath));
-    if (layer === "Delivery") {
+    if (layer2 === "Delivery") {
       if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
       if (WORK_ITEM_TYPES2.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
         if (a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) slot.hasWorkItem = true;
       }
       continue;
     }
-    if (type === CONSOLIDATED_TYPE[layer]) slot.consolidated = true;
-    else if (STRUCTURED_TYPES[layer].has(type)) slot.structured = true;
+    if (type === CONSOLIDATED_TYPE[layer2]) slot.consolidated = true;
+    else if (STRUCTURED_TYPES[layer2].has(type)) slot.structured = true;
     else if (!type) {
       slot.consolidated = true;
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
   if (existsDirWithMd(join(dir, KNOWLEDGE, "tech", "decisions"))) acc.Tech.structured = true;
-  return ["Business", "Product", "Tech", "Delivery"].map((layer) => ({
-    layer,
-    status: statusFor(layer, acc[layer]),
-    detected: [...acc[layer].detected].sort()
+  return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
+    layer: layer2,
+    status: statusFor(layer2, acc[layer2]),
+    detected: [...acc[layer2].detected].sort()
   }));
 }
 function blank() {
@@ -4830,8 +5024,8 @@ function existsDirWithMd(d) {
     return false;
   }
 }
-function statusFor(layer, a) {
-  if (layer === "Delivery") {
+function statusFor(layer2, a) {
+  if (layer2 === "Delivery") {
     if (a.hasWorkItem) return "Traceable";
     if (a.hasRoadmap) return "Partial";
     return "Missing";
@@ -4840,40 +5034,15 @@ function statusFor(layer, a) {
   if (a.consolidated) return "Consolidated";
   return "Missing";
 }
-function roadmapHasUnmaterializedCandidates(dir) {
-  const roadmap = join(dir, KNOWLEDGE, "delivery", "roadmap.md");
-  if (!exists(roadmap)) return false;
-  let hasCandidates = false;
-  try {
-    hasCandidates = /WI-[A-Z0-9-]*\d/i.test(readFile(roadmap));
-  } catch {
-    return false;
-  }
-  if (!hasCandidates) return false;
-  const wiDir = join(dir, KNOWLEDGE, "delivery", "work-items");
-  return !existsDirWithMd(wiDir);
-}
 
 // src/core/layers.ts
 function knowledgeLayers(dir) {
   return discoverLayers(dir);
 }
-var COMPLETE = {
-  Business: (s) => s !== "Missing",
-  Product: (s) => s !== "Missing",
-  Tech: (s) => s !== "Missing",
-  Delivery: (s) => s === "Traceable"
-};
-function currentPhase(layers) {
-  for (const l of layers) {
-    if (!COMPLETE[l.layer](l.status)) return l.layer;
-  }
-  return "Delivery";
-}
 function renderLayersMarkdown(layers) {
   const lines = [];
-  for (const { layer, status, detected } of layers) {
-    lines.push(`### ${layer} \u2014 ${status}`);
+  for (const { layer: layer2, status, detected } of layers) {
+    lines.push(`### ${layer2} \u2014 ${status}`);
     if (detected.length > 0) for (const d of detected) lines.push(`- \u2713 ${d}`);
     else lines.push("- \u2717 none");
     lines.push("");
@@ -4881,54 +5050,8 @@ function renderLayersMarkdown(layers) {
   return lines.join("\n").trimEnd();
 }
 
-// src/core/lifecycle.ts
-var LIFECYCLE_STATES = [
-  "draft",
-  "ready",
-  "in-progress",
-  "blocked",
-  "completed",
-  "archived"
-];
-var ACTIVE_STATES = ["draft", "ready", "in-progress", "blocked"];
-var LEGACY_STATUS_MAP = {
-  done: "completed",
-  cancelled: "archived",
-  canceled: "archived",
-  "in-progress": "in-progress"
-};
-var STATE_SET = new Set(LIFECYCLE_STATES);
-function isLifecycleState(s) {
-  return STATE_SET.has(s);
-}
-function isActiveState(s) {
-  return ACTIVE_STATES.includes(s);
-}
-function lifecycleFolderOf(filePath) {
-  const p2 = filePath.replace(/\\/g, "/");
-  const m = p2.match(/\/delivery\/work-items\/([^/]+)\//);
-  if (m && isLifecycleState(m[1])) return m[1];
-  return null;
-}
-function lifecycleStateOf(item) {
-  const status = (item.status ?? "").trim().toLowerCase();
-  if (isLifecycleState(status)) return status;
-  if (status && LEGACY_STATUS_MAP[status]) return LEGACY_STATUS_MAP[status];
-  const folder = lifecycleFolderOf(item.filePath ?? "");
-  if (folder) return folder;
-  return "ready";
-}
-function emptyLifecycleCounts() {
-  return Object.fromEntries(LIFECYCLE_STATES.map((s) => [s, 0]));
-}
-function lifecycleCounts(states) {
-  const counts = emptyLifecycleCounts();
-  for (const s of states) counts[s]++;
-  return counts;
-}
-
 // src/core/project-explain.ts
-var ARCH_DIR3 = "knowledge";
+var ARCH_DIR4 = "knowledge";
 function first(values) {
   if (Array.isArray(values)) {
     const v = values.find((x) => typeof x === "string" && x);
@@ -4959,7 +5082,7 @@ function loadScan(dir) {
   }
 }
 function hasAgents(dir) {
-  const agentsDir = join(dir, ARCH_DIR3, "agents");
+  const agentsDir = join(dir, ARCH_DIR4, "agents");
   if (!exists(agentsDir)) return false;
   function hasAgentMd(d) {
     for (const e of readDir(d)) {
@@ -4996,7 +5119,7 @@ function buildProjectExplanation(dir) {
   const layerStatus = (name) => layers.find((l) => l.layer === name)?.status ?? "Missing";
   const knowledge = {
     hasScan: scan2 !== null,
-    hasInventory: exists(join(dir, ARCH_DIR3, "inventory.md")),
+    hasInventory: exists(join(dir, ARCH_DIR4, "inventory.md")),
     hasContextPack: exists(join(dir, ".kaddo", "context-pack.md")),
     hasUnderstand: exists(join(dir, ".kaddo", "understand.md")),
     hasCapabilities: layerStatus("Product") !== "Missing",
@@ -5004,12 +5127,7 @@ function buildProjectExplanation(dir) {
     hasRoadmap: layerStatus("Delivery") !== "Missing",
     hasAgents: hasAgents(dir)
   };
-  const archDir = join(dir, ARCH_DIR3);
-  const allArtifacts = exists(archDir) ? readArtifacts(archDir) : [];
-  const workItemArtifacts = allArtifacts.filter((a) => {
-    const p2 = a.filePath.replace(/\\/g, "/");
-    return p2.includes("/delivery/work-items/") && Boolean(a.type);
-  });
+  const workItemArtifacts = discoverWorkItems(dir);
   const items = workItemArtifacts.map((a) => ({
     id: a.id || a.title,
     title: a.title,
@@ -5051,7 +5169,7 @@ function buildProjectExplanation(dir) {
     workItemsMissingOwnership: items.length - withOwnership
   };
   const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
-  const roadmapPath = join(dir, ARCH_DIR3, "delivery", "roadmap.md");
+  const roadmapPath = join(dir, ARCH_DIR4, "delivery", "roadmap.md");
   const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
   const roadmap = roadmapStats(roadmapMd, items.length);
   const mappedModules = loadMappedModules(dir);
@@ -5232,6 +5350,15 @@ function renderExplanationHuman(exp) {
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
     lines.push("");
   }
+  const assessment = assessPhase(exp);
+  lines.push("## Phase");
+  lines.push(`- Phase: ${assessment.phase}`);
+  if (assessment.reasons.length > 0) {
+    lines.push("- Reason:");
+    for (const r of assessment.reasons) lines.push(`  - ${r}`);
+  }
+  if (assessment.nextStep) lines.push(`- Next step: ${assessment.nextStep}`);
+  lines.push("");
   if (exp.suggestedNextSteps.length > 0) {
     lines.push("## Suggested Next Steps");
     exp.suggestedNextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
@@ -5245,10 +5372,10 @@ function renderExplanationAgent(exp) {
 }
 
 // src/commands/explain.ts
-var ARCH_DIR4 = "knowledge";
+var ARCH_DIR5 = "knowledge";
 var CONFIG_PATH3 = ".kaddo/config.yml";
 function readKnowledge(dir) {
-  const knowledgePath = join(dir, ARCH_DIR4, "knowledge.md");
+  const knowledgePath = join(dir, ARCH_DIR5, "knowledge.md");
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
@@ -5259,7 +5386,7 @@ function readKnowledge(dir) {
   }
 }
 function readRoadmap(dir) {
-  const roadmapPath = join(dir, ARCH_DIR4, "roadmap.md");
+  const roadmapPath = join(dir, ARCH_DIR5, "roadmap.md");
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
@@ -5408,7 +5535,7 @@ function runExplain(opts) {
     explainProject(dir, mode);
     return;
   }
-  const archDir = join(dir, ARCH_DIR4);
+  const archDir = join(dir, ARCH_DIR5);
   if (!exists(archDir)) {
     console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
@@ -5433,7 +5560,7 @@ function runExplain(opts) {
 // src/core/context-pack.ts
 import matter3 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
-var ARCH_DIR5 = "knowledge";
+var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
   const scanPath = join(dir, ".kaddo", "scan.json");
   if (!exists(scanPath)) return null;
@@ -5449,7 +5576,7 @@ function firstParagraph(markdown) {
   return para ?? "";
 }
 function readMarkdownSummary(dir, file) {
-  const p2 = join(dir, ARCH_DIR5, file);
+  const p2 = join(dir, ARCH_DIR6, file);
   if (!exists(p2)) return null;
   try {
     return firstParagraph(readFile(p2));
@@ -5527,7 +5654,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     missing.push("Scan baseline missing. Run `kaddo scan` for better context.");
   }
   const detected = scanJson?.detected ?? {};
-  const inventoryAvailable = exists(join(dir, ARCH_DIR5, "inventory.md"));
+  const inventoryAvailable = exists(join(dir, ARCH_DIR6, "inventory.md"));
   if (!inventoryAvailable) {
     missing.push("No technical inventory found. Run `kaddo scan` to generate it.");
   }
@@ -5539,8 +5666,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   if (!roadmapSummary) {
     missing.push("No roadmap baseline found.");
   }
-  const archPath = join(dir, ARCH_DIR5);
-  const allArtifacts = exists(archPath) ? readArtifacts(archPath) : [];
+  const allArtifacts = discoverKnowledge(dir);
   const workItems = allArtifacts.filter(
     (a) => isDeliveryWorkItem(a) && isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))
   );
@@ -5548,7 +5674,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
-  const roadmapPath = join(dir, ARCH_DIR5, "delivery", "roadmap.md");
+  const roadmapPath = join(dir, ARCH_DIR6, "delivery", "roadmap.md");
   const materialized = allArtifacts.filter(
     (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
   ).length;
@@ -5562,6 +5688,28 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   }
   const mappedModules = loadMappedModules(dir);
   const layers = knowledgeLayers(dir);
+  const allWorkItems = allArtifacts.filter((a) => a.isWorkItem);
+  const wiWithOwnership = allWorkItems.filter((a) => a.codeGlobs.length > 0).length;
+  const phase = assessPhase({
+    layers,
+    roadmap,
+    workItems: {
+      total: allWorkItems.length,
+      byState: lifecycleCounts(
+        allWorkItems.map((a) => lifecycleStateOf({ status: a.status, filePath: a.filePath }))
+      ),
+      items: allWorkItems.map((a) => ({
+        id: a.id || a.title,
+        title: a.title,
+        lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath })
+      }))
+    },
+    ownership: {
+      workItemsTotal: allWorkItems.length,
+      workItemsWithOwnership: wiWithOwnership,
+      workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
+    }
+  });
   return {
     version: CONTEXT_PACK_VERSION,
     generatedAt: now.toISOString(),
@@ -5590,6 +5738,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     },
     layers,
     roadmap,
+    phase,
     deliveryMix,
     mappedModules,
     missing,
@@ -5627,6 +5776,21 @@ function renderContextPack(pack) {
       `- Structure: ${project.structure}`
     ].join("\n") + "\n"
   );
+  parts.push("## Current Phase\n");
+  parts.push(`Phase: ${pack.phase.phase}
+`);
+  if (pack.phase.reasons.length > 0) {
+    parts.push("Reason:\n");
+    parts.push(pack.phase.reasons.map((r) => `- ${r}`).join("\n") + "\n");
+  }
+  if (pack.phase.recommendedAgents.length > 0) {
+    parts.push(`Recommended next: ${pack.phase.recommendedAgents.join(", ")}
+`);
+  }
+  if (pack.phase.nextStep) {
+    parts.push(`Next step: ${pack.phase.nextStep}
+`);
+  }
   parts.push("## Knowledge Layers\n");
   parts.push(
     "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
@@ -5942,19 +6106,12 @@ import { parse as parseYaml9 } from "yaml";
 function slugify2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function isWorkItem(a) {
-  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
-}
 function toActive(a) {
   const id = a.id || a.title || "WI";
   return { id, title: a.title || id, type: a.type, slug: slugify2(a.title || id) };
 }
 function activeWorkItems(dir) {
-  const archDir = join(dir, "knowledge");
-  if (!exists(archDir)) return [];
-  return readArtifacts(archDir).filter(
-    (a) => isWorkItem(a) && lifecycleStateOf({ status: a.status, filePath: a.filePath }) === "in-progress"
-  ).map(toActive);
+  return discoverWorkItems(dir).filter((a) => a.lifecycle === "in-progress").map(toActive);
 }
 function branchPrefix(type) {
   switch (type) {
@@ -6033,64 +6190,19 @@ function runUnderstand() {
     );
   }
   console.log(renderUnderstandTerminal(plan));
-  const phase = currentPhase(knowledgeLayers(dir));
-  const group = phase.toLowerCase();
-  const groupAgents = (AGENT_GROUPS[group] ?? []).map((a) => a.replace(/\.md$/, ""));
-  const NEXT_STEPS = {
-    business: ["Use business-agent \u2192 refine knowledge/business/business.md"],
-    product: [
-      "Use bootstrap-agent \u2192 refine knowledge/product/product.md",
-      "Use capability-agent \u2192 knowledge/product/capabilities.md"
-    ],
-    tech: [
-      "Use architecture-agent \u2192 knowledge/tech/current-state.md (reality)",
-      "Use codebase-agent \u2192 knowledge/tech/codebase.md (intent)",
-      "Record decisions as ADRs in knowledge/tech/decisions/"
-    ],
-    delivery: [
-      "Use roadmap-agent \u2192 knowledge/delivery/roadmap.md",
-      "Run `kaddo create --from roadmap` (candidates \u2192 Work Items)",
-      "Use work-item-agent \u2192 refine into knowledge/delivery/work-items/",
-      "Use implementation-agent \u2192 implement, then `kaddo scan`, `kaddo owners suggest`, `kaddo guard`"
-    ],
-    utilities: ["Use legacy-agent to surface risks and unknowns"]
-  };
-  if (roadmapHasUnmaterializedCandidates(dir)) {
-    const { candidates, materialized, remaining } = pack.roadmap;
-    console.log("");
-    console.log(
-      `The roadmap has ${remaining} unmaterialized Work Item candidate(s) (${candidates} candidate(s), ${materialized} materialized).`
-    );
-    console.log("  \u2192 Run `kaddo create --from roadmap`, or use the work-item-agent to");
-    console.log("    materialize them into knowledge/delivery/work-items/.");
-  }
+  const exp = buildProjectExplanation(dir);
+  const assessment = assessPhase(exp);
   console.log("");
-  console.log(`Current phase: ${phase}`);
-  console.log("Recommended next steps:");
-  console.log("  1. Run `kaddo scan`   (technical signals \u2192 knowledge/inventory.md)");
-  console.log("  2. Run `kaddo context`  (package knowledge for your LLM)");
-  let n = 3;
-  for (const step of NEXT_STEPS[group] ?? []) console.log(`  ${n++}. ${step}`);
-  if (groupAgents.length > 0) {
-    console.log(`Agents for this phase: ${groupAgents.join(", ")}`);
+  console.log(`Current phase: ${assessment.phase}`);
+  if (assessment.reasons.length > 0) {
+    console.log("Reason:");
+    for (const r of assessment.reasons) console.log(`  - ${r}`);
   }
-  const exp = buildProjectExplanation(dir);
-  if (exp.workItems.total > 0) {
-    const bs = exp.workItems.byState;
-    console.log("");
-    console.log("Current active work:");
-    console.log(`  Draft: ${bs.draft}  Ready: ${bs.ready}  In Progress: ${bs["in-progress"]}  Blocked: ${bs.blocked}`);
-    const firstReady = exp.workItems.items.find((i) => i.lifecycle === "ready");
-    const firstInProgress = exp.workItems.items.find((i) => i.lifecycle === "in-progress");
-    if (firstInProgress) {
-      console.log(`  \u2192 Continue ${firstInProgress.id} \u2014 ${firstInProgress.title} (in progress).`);
-    } else if (firstReady) {
-      console.log(`  \u2192 Recommended next step: start ${firstReady.id} \u2014 ${firstReady.title}.`);
-    } else if (bs.draft > 0) {
-      console.log("  \u2192 Refine a draft Work Item to `ready` (scope + acceptance defined).");
-    } else if (bs.blocked > 0) {
-      console.log("  \u2192 All active work is blocked. Resolve the blockers to move forward.");
-    }
+  if (assessment.recommendedAgents.length > 0) {
+    console.log(`Recommended: ${assessment.recommendedAgents.join(", ")}`);
+  }
+  if (assessment.nextStep) {
+    console.log(`Next step: ${assessment.nextStep}`);
   }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
@@ -6257,9 +6369,9 @@ function classify(declaredType, declaredLevel, touchedFiles) {
 }
 
 // src/commands/classify.ts
-var ARCH_DIR6 = "knowledge";
+var ARCH_DIR7 = "knowledge";
 function findActiveWorkItem(dir) {
-  const archDir = join(dir, ARCH_DIR6);
+  const archDir = join(dir, ARCH_DIR7);
   if (!exists(archDir)) return null;
   const artifacts = readArtifacts(archDir);
   return artifacts.filter((a) => a.status === "in-progress" && a.type !== "current-state" && a.type !== "roadmap").sort((a, b) => {
@@ -6325,7 +6437,7 @@ async function runClassify(opts = {}) {
 
 // src/commands/status.ts
 import { parse as parseYaml10 } from "yaml";
-var ARCH_DIR7 = "knowledge";
+var ARCH_DIR8 = "knowledge";
 var CONFIG_PATH4 = ".kaddo/config.yml";
 function loadConfig3(dir) {
   const p2 = join(dir, CONFIG_PATH4);
@@ -6338,12 +6450,12 @@ function loadConfig3(dir) {
 }
 function runStatus() {
   const dir = cwd();
-  if (!exists(join(dir, ARCH_DIR7))) {
+  if (!exists(join(dir, ARCH_DIR8))) {
     console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   const config = loadConfig3(dir);
-  const artifacts = readArtifacts(join(dir, ARCH_DIR7));
+  const artifacts = readArtifacts(join(dir, ARCH_DIR8));
   const ignores = loadIgnores(dir);
   const workItems = artifacts.filter(
     (a) => a.type !== "current-state" && a.type !== "roadmap"
@@ -6389,7 +6501,7 @@ function runStatus() {
 
 // src/commands/learn.ts
 import matter4 from "gray-matter";
-var ARCH_DIR8 = "knowledge";
+var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
   const wiDir = join(dir, WORK_ITEMS_DIR2);
@@ -6430,12 +6542,12 @@ ${learning.trim()}
 }
 async function runLearn(artifactId) {
   const dir = cwd();
-  if (!exists(join(dir, ARCH_DIR8))) {
+  if (!exists(join(dir, ARCH_DIR9))) {
     console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
   intro2("kaddo learn");
-  const artifacts = readArtifacts(join(dir, ARCH_DIR8));
+  const artifacts = readArtifacts(join(dir, ARCH_DIR9));
   const inProgress = artifacts.filter(
     (a) => a.status === "in-progress" && a.type !== "current-state" && a.type !== "roadmap"
   );
@@ -6478,7 +6590,7 @@ async function runLearn(artifactId) {
 }
 
 // src/commands/history.ts
-var ARCH_DIR9 = "knowledge";
+var ARCH_DIR10 = "knowledge";
 function formatRow(a) {
   const id = (a.id || "").padEnd(8);
   const type = a.type.padEnd(18);
@@ -6489,11 +6601,11 @@ function formatRow(a) {
 }
 function runHistory(opts = {}) {
   const dir = cwd();
-  if (!exists(join(dir, ARCH_DIR9))) {
+  if (!exists(join(dir, ARCH_DIR10))) {
     console.error("No knowledge/ directory found. Run `kaddo init` first.");
     process.exit(1);
   }
-  let artifacts = readArtifacts(join(dir, ARCH_DIR9)).filter(
+  let artifacts = readArtifacts(join(dir, ARCH_DIR10)).filter(
     (a) => a.type !== "current-state" && a.type !== "roadmap"
   );
   if (opts.domain) {
@@ -6654,42 +6766,23 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 
 // src/core/ownership-suggest.ts
 import matter5 from "gray-matter";
-var WORK_ITEMS_DIR3 = "knowledge/delivery/work-items";
 var SCAN_PATH = ".kaddo/scan.json";
 function toStringArray3(value) {
   return Array.isArray(value) ? value.map((v) => String(v)).filter(Boolean) : [];
 }
-function parseOwnershipArtifact(filePath, relPath, raw) {
-  try {
-    const { data } = matter5(raw);
-    const codeGlobs = toStringArray3(data.code);
-    return {
-      filePath,
-      relPath: relPath.split("\\").join("/"),
-      id: String(data.id ?? ""),
-      title: String(data.title ?? ""),
-      type: String(data.type ?? ""),
-      domains: toStringArray3(data.domains),
-      capabilities: toStringArray3(data.capabilities),
-      codeGlobs,
-      source: data.source ? String(data.source) : void 0,
-      hasOwnership: codeGlobs.length > 0
-    };
-  } catch {
-    return null;
-  }
-}
 function findWorkItemArtifacts(dir) {
-  const wiDir = join(dir, WORK_ITEMS_DIR3);
-  if (!exists(wiDir)) return [];
-  const artifacts = [];
-  for (const entry of readDir(wiDir)) {
-    const full = join(wiDir, entry);
-    if (!isFile(full) || !entry.endsWith(".md")) continue;
-    const parsed = parseOwnershipArtifact(full, `${WORK_ITEMS_DIR3}/${entry}`, readFile(full));
-    if (parsed) artifacts.push(parsed);
-  }
-  return artifacts;
+  return discoverWorkItems(dir).map((a) => ({
+    filePath: a.filePath,
+    relPath: a.relPath,
+    id: a.id,
+    title: a.title,
+    type: a.type,
+    domains: a.domains,
+    capabilities: a.capabilities,
+    codeGlobs: a.codeGlobs,
+    source: a.source || void 0,
+    hasOwnership: a.codeGlobs.length > 0
+  }));
 }
 function artifactsMissingOwnership(artifacts) {
   return artifacts.filter((a) => !a.hasOwnership);
@@ -6833,16 +6926,24 @@ async function runOwnersSuggest() {
   intro2("kaddo owners suggest");
   const artifacts = findWorkItemArtifacts(dir);
   if (artifacts.length === 0) {
-    log2.warn("No knowledge artifacts found. Create a Work Item first.");
+    log2.warn(
+      "No Work Items found under knowledge/delivery/work-items/ (searched recursively, including draft/ ready/ in-progress/ \u2026)."
+    );
+    log2.info("Create one with `kaddo create` or `kaddo create --from roadmap`.");
     outro2("Nothing to do.");
     return;
   }
   const missing = artifactsMissingOwnership(artifacts);
   if (missing.length === 0) {
-    log2.info("All detected artifacts already declare code ownership.");
+    log2.success(
+      `Found ${artifacts.length} Work Item${artifacts.length === 1 ? "" : "s"}; all already declare code ownership.`
+    );
     outro2("Nothing to do.");
     return;
   }
+  log2.info(
+    `Found ${artifacts.length} Work Item${artifacts.length === 1 ? "" : "s"}; ${missing.length} missing code ownership.`
+  );
   const relPath = missing.length === 1 ? missing[0].relPath : await select2({
     message: "Which artifact needs ownership?",
     options: missing.map((a) => ({
@@ -8769,7 +8870,7 @@ async function runBootstrap(dir = cwd()) {
   const result = bootstrap(dir);
   console.log("");
   console.log("Bootstrap layers:");
-  for (const layer of result.layers) console.log(`  \u2713 ${layer}`);
+  for (const layer2 of result.layers) console.log(`  \u2713 ${layer2}`);
   console.log("");
   if (result.written.length > 0) {
     console.log("Created:");

package/package.json

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