@kaddo/cli 3.9.1 → 3.10.1

package/dist/index.js

@@ -4814,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 = {
@@ -4877,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() {
@@ -4920,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";
@@ -4930,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("");
@@ -5271,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}`));
@@ -5600,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(),
@@ -5628,6 +5738,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     },
     layers,
     roadmap,
+    phase,
     deliveryMix,
     mappedModules,
     missing,
@@ -5665,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"
@@ -5850,7 +5976,7 @@ function flowForState(state) {
 }
 function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
-  const flow = flowForState(state);
+  const flow = flowForState(state).filter((s) => !exists(join(dir, s.output)));
   const steps = flow.map((s) => {
     const installed = agentIsInstalled(dir, s.agent);
     return { agent: s.agent, output: s.output, installed };
@@ -5951,24 +6077,26 @@ function renderUnderstandTerminal(plan) {
   lines.push(`Team: ${project.teamSize}`);
   lines.push(`Structure: ${project.structure}`);
   lines.push("");
-  lines.push("Recommended flow:");
-  steps.forEach((s, i) => {
-    const flag = s.installed ? "" : "  (not installed)";
-    lines.push(`  ${i + 1}. ${agentName(s.agent)} \u2192 ${s.output}${flag}`);
-  });
-  lines.push("");
   const first2 = steps[0];
   if (first2) {
+    lines.push("Foundational knowledge still needed:");
+    steps.forEach((s, i) => {
+      const flag = s.installed ? "" : "  (not installed)";
+      lines.push(`  ${i + 1}. ${agentName(s.agent)} \u2192 ${s.output}${flag}`);
+    });
+    lines.push("");
     lines.push(`First step: use ${agentName(first2.agent)}.`);
     lines.push("");
     lines.push(`  Context:         ${plan.contextPackPath}`);
     lines.push(`  Agent prompt:    knowledge/agents/${first2.agent}`);
     lines.push(`  Expected output: ${first2.output}`);
     lines.push("");
+    lines.push("Instructions:");
+    lines.push("  Open your preferred LLM chat, paste the context pack, then paste the agent");
+    lines.push("  prompt. Ask the LLM to generate the expected output and save it in the target file.");
+  } else {
+    lines.push("Foundational knowledge looks complete \u2014 see the phase recommendation below.");
   }
-  lines.push("Instructions:");
-  lines.push("  Open your preferred LLM chat, paste the context pack, then paste the agent");
-  lines.push("  prompt. Ask the LLM to generate the expected output and save it in the target file.");
   lines.push("");
   lines.push("Kaddo does not call an LLM. You stay in control of the interpretation.");
   lines.push("");
@@ -6064,64 +6192,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) {
@@ -8789,7 +8872,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.1",
+  "version": "3.10.1",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {