@kaddo/cli 3.5.1 → 3.7.0

package/dist/index.js

@@ -1907,7 +1907,9 @@ existing Work Item file to refine.
 
 ## Expected Output
 
-A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md\`.
+A refined Work Item intended to be saved under the lifecycle workspace:
+\`knowledge/delivery/work-items/draft/\`, \`ready/\`, \`in-progress/\`, \`blocked/\`,
+\`completed/\` or \`archived/\`.
 
 ## Instructions
 
@@ -1915,9 +1917,10 @@ A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md
 2. Split the candidate if it is too large for a single Work Item.
 3. Validate the Knowledge Level (K0\u2013K4) and propose a different one if needed.
 4. Propose acceptance criteria.
-5. Propose a Definition of Done.
-6. Identify open questions and assumptions.
-7. Suggest ownership candidates (code globs) if evident.
+5. Propose Out of scope and Validation sections.
+6. Propose a Definition of Done.
+7. Identify open questions and assumptions.
+8. Suggest ownership candidates (code globs) if evident.
 
 ## Constraints
 
@@ -1939,6 +1942,10 @@ A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md
 
 **Acceptance criteria:**
 
+**Out of scope:**
+
+**Validation:**
+
 **Definition of Done:**
 
 **Open questions:**
@@ -1948,7 +1955,9 @@ A refined Work Item intended to be saved as \`knowledge/delivery/work-items/*.md
 
 ## Where to Save the Result
 
-Save the output as a file under \`knowledge/delivery/work-items/\`.
+Save new output as a draft under \`knowledge/delivery/work-items/draft/\` unless a human
+explicitly asks for another lifecycle state. Treat only \`draft\`, \`ready\`, \`in-progress\`
+and \`blocked\` as active work; \`completed\` and \`archived\` are historical knowledge.
 
 ## Delivery workflow
 
@@ -3093,12 +3102,96 @@ function parseBlock(block) {
     openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0
   }));
 }
+var WI_ID_RE = /\bWI-[A-Za-z0-9-]*\d/;
+var HEADING_RE = /^#{2,4}\s+(.*)$/;
+var FLEX_BULLET_RE = /^\s*[-*]\s+(?:\[[ xX]?\]\s+)?(WI-[A-Za-z0-9-]*\d)\b[\s:.\-–)]*\s*(.*)$/;
+var SEPARATOR_CELL_RE = /^:?-{2,}:?$/;
+function splitRow(line) {
+  return line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((c) => c.trim());
+}
+function isSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((c) => SEPARATOR_CELL_RE.test(c) || c === "");
+}
+function initiativeFromHeading(text3) {
+  const rm = text3.match(/^(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/);
+  if (rm) return { id: rm[1], title: rm[2].trim() || void 0 };
+  return { title: text3.trim() || void 0 };
+}
+function extractDeps(cell) {
+  if (!cell) return void 0;
+  const ids = cell.match(/WI-[A-Za-z0-9-]*\d/g);
+  return ids && ids.length ? [...new Set(ids)] : void 0;
+}
+function parseFlexible(markdown) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let initiative;
+  let cols = null;
+  const push = (id, title, deps, raw) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push({
+      id,
+      title: title.trim() || id,
+      dependencies: deps,
+      initiative: initiative?.id || initiative?.title ? { ...initiative } : void 0,
+      rawMarkdown: raw.trim()
+    });
+  };
+  for (const line of markdown.split(/\r?\n/)) {
+    const h = line.match(HEADING_RE);
+    if (h) {
+      initiative = initiativeFromHeading(h[1]);
+      cols = null;
+      continue;
+    }
+    if (line.includes("|")) {
+      const cells = splitRow(line);
+      if (isSeparatorRow(cells)) continue;
+      const lower = cells.map((c) => c.toLowerCase());
+      const idIdx = lower.findIndex((c) => c === "id" || c === "wi" || c === "work item id");
+      if (idIdx >= 0 && !WI_ID_RE.test(line)) {
+        cols = {
+          id: idIdx,
+          title: lower.findIndex((c) => /work item|title|item|name|description/.test(c)),
+          deps: lower.findIndex((c) => /depend/.test(c))
+        };
+        continue;
+      }
+      if (WI_ID_RE.test(line)) {
+        let idCell = cols && cols.id >= 0 ? cells[cols.id] : cells.find((c) => /^WI-/.test(c));
+        const idMatch = (idCell ?? line).match(/WI-[A-Za-z0-9-]*\d/);
+        if (!idMatch) continue;
+        const id = idMatch[0];
+        const title = cols && cols.title >= 0 ? cells[cols.title] ?? "" : cells.find((c) => !/^WI-/.test(c) && c) ?? "";
+        const deps = cols && cols.deps >= 0 ? extractDeps(cells[cols.deps]) : void 0;
+        push(id, title, deps, line);
+        continue;
+      }
+      continue;
+    }
+    const b = line.match(FLEX_BULLET_RE);
+    if (b) {
+      push(b[1], b[2] ?? "", void 0, line);
+      continue;
+    }
+  }
+  return out;
+}
 function parseRoadmapCandidates(markdown) {
-  return splitInitiatives(markdown).flatMap(parseBlock);
+  const strict = splitInitiatives(markdown).flatMap(parseBlock);
+  if (strict.length > 0) return strict;
+  return parseFlexible(markdown);
+}
+function roadmapStats(markdown, materialized) {
+  if (markdown == null) return { present: false, candidates: 0, materialized, remaining: 0 };
+  const candidates = parseRoadmapCandidates(markdown).length;
+  return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
 }
 
 // src/commands/create.ts
 var WORK_ITEMS_DIR = "knowledge/delivery/work-items";
+var DRAFT_DIR = `${WORK_ITEMS_DIR}/draft`;
 var ROADMAP_PATH = "knowledge/delivery/roadmap.md";
 function printStateGuidance(dir) {
   let config;
@@ -3117,13 +3210,20 @@ function printStateGuidance(dir) {
 function nextWorkItemId(dir) {
   const wiDir = join(dir, WORK_ITEMS_DIR);
   if (!exists(wiDir)) return "WI-001";
-  const files = readDir(wiDir).filter((f) => f.endsWith(".md"));
-  const nums = files.map((f) => {
-    const m = f.match(/WI-(\d+)/);
-    return m ? parseInt(m[1], 10) : 0;
-  }).filter((n) => n > 0);
-  const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
-  return `WI-${String(next).padStart(3, "0")}`;
+  let max = 0;
+  const walk = (d) => {
+    for (const entry of readDir(d)) {
+      const full = join(d, entry);
+      if (isFile(full)) {
+        const m = entry.match(/WI-(\d+)/);
+        if (m) max = Math.max(max, parseInt(m[1], 10));
+      } else if (!entry.startsWith(".")) {
+        walk(full);
+      }
+    }
+  };
+  walk(wiDir);
+  return `WI-${String(max + 1).padStart(3, "0")}`;
 }
 function slugify(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
@@ -3139,7 +3239,9 @@ function buildFrontMatter(id, type, level, title, answers) {
     `id: ${id}`,
     `title: "${title}"`,
     `knowledge_level: ${level}`,
-    `status: in-progress`,
+    `status: draft`,
+    `phase: now`,
+    `initiative:`,
     `domains: []`,
     `code: []`,
     `created_at: ${today}`,
@@ -3191,6 +3293,14 @@ ${answers.design}
 ${answers.risks}
 `);
   }
+  sections.push(`## Out of scope
+
+_Not included in this Work Item._
+`);
+  sections.push(`## Validation
+
+_How will this be validated?_
+`);
   if (qualityGate.length > 0) {
     sections.push(`## Definition of Done
 
@@ -3215,7 +3325,9 @@ function buildModuleFrontMatter(id, modType, title, answers) {
     `id: ${id}`,
     `title: "${title}"`,
     `knowledge_level: ${modType.knowledgeLevel}`,
-    `status: in-progress`,
+    `status: draft`,
+    `phase: now`,
+    `initiative:`,
     `domains: []`,
     `code: []`,
     `created_at: ${today}`,
@@ -3247,6 +3359,14 @@ ${answer}
 ${modType.qualityGate.map((g) => `- [ ] ${g}`).join("\n")}
 `);
   }
+  sections.push(`## Out of scope
+
+_Not included in this Work Item._
+`);
+  sections.push(`## Validation
+
+_How will this be validated?_
+`);
   sections.push(`## Learning
 
 _What did we learn from this change? Update after completion._
@@ -3296,7 +3416,7 @@ async function runCreate(type, opts = {}) {
   const id = nextWorkItemId(dir);
   const slug = slugify(title);
   const fileName = `${id}-${slug}.md`;
-  const filePath = join(dir, WORK_ITEMS_DIR, fileName);
+  const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildFrontMatter(id, workItemType, level, title.trim(), answers);
   const body = buildBody(workItemType, level, title.trim(), answers, levelDef.qualityGate);
   const content = `${frontMatter2}
@@ -3307,7 +3427,8 @@ ${body}`;
     process.exit(1);
   }
   writeFile(filePath, content);
-  log2.success(`Created ${WORK_ITEMS_DIR}/${fileName}`);
+  log2.success(`Created ${DRAFT_DIR}/${fileName}`);
+  log2.info(`New Work Items start in \`draft\`. Move to \`ready\` when scope and acceptance are set.`);
   log2.info(`Add code globs to the front matter \`code:\` field to enable Guard Lite.`);
   outro2(`Work item ${id} created.`);
 }
@@ -3336,14 +3457,14 @@ async function runCreateModule(dir, modType) {
   const id = nextWorkItemId(dir);
   const slug = slugify(title);
   const fileName = `${id}-${slug}.md`;
-  const filePath = join(dir, WORK_ITEMS_DIR, fileName);
+  const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildModuleFrontMatter(id, modType, title.trim(), answers);
   const body = buildModuleBody(modType, title.trim(), answers);
   const content = `${frontMatter2}
 
 ${body}`;
   writeFile(filePath, content);
-  log2.success(`Created ${WORK_ITEMS_DIR}/${fileName}`);
+  log2.success(`Created ${DRAFT_DIR}/${fileName}`);
   log2.info(`Add code globs to the front matter \`code:\` field to enable Guard Lite.`);
   outro2(`Work item ${id} created.`);
 }
@@ -3361,13 +3482,16 @@ function resolveCandidateLevel(candidate, type) {
 function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = (answers.problem?.split(".")[0] ?? candidate.expectedValue ?? title).trim();
+  const initiative = candidate.initiative?.title ?? candidate.initiative?.id ?? "";
   const lines = [
     "---",
     `type: ${type}`,
     `id: ${id}`,
     `title: "${title}"`,
     `knowledge_level: ${level}`,
-    `status: in-progress`,
+    `status: draft`,
+    `phase: now`,
+    `initiative: "${initiative.replace(/"/g, "'")}"`,
     `domains: []`,
     `code: []`,
     `created_at: ${today}`,
@@ -3442,6 +3566,14 @@ ${candidate.notes}
     sections.push(`## Open Questions
 
 ${formatList(candidate.openQuestions)}
+`);
+  sections.push(`## Out of scope
+
+_Not included in this Work Item._
+`);
+  sections.push(`## Validation
+
+_How will this be validated?_
 `);
   if (qualityGate.length > 0)
     sections.push(`## Definition of Done
@@ -3524,8 +3656,8 @@ async function runCreateFromRoadmap(dir, cliType) {
   }
   const id = nextWorkItemId(dir);
   const { fileName, content } = buildRoadmapWorkItem({ id, type, level, candidate, answers });
-  writeFile(join(dir, WORK_ITEMS_DIR, fileName), content);
-  log2.success(`Created ${WORK_ITEMS_DIR}/${fileName}`);
+  writeFile(join(dir, DRAFT_DIR, fileName), content);
+  log2.success(`Created ${DRAFT_DIR}/${fileName}`);
   log2.info(`Traced to roadmap candidate ${candidate.id}${candidate.initiative?.id ? ` (initiative ${candidate.initiative.id})` : ""}.`);
   log2.info(`Add code globs to the front matter \`code:\` field to enable Guard Lite.`);
   outro2(`Work item ${id} created from roadmap.`);
@@ -3593,7 +3725,9 @@ function parseArtifact(filePath, raw) {
       knowledgeLevel: String(data.knowledge_level ?? ""),
       codeGlobs: globs,
       domains: Array.isArray(data.domains) ? data.domains : [],
-      status: String(data.status ?? "")
+      status: String(data.status ?? ""),
+      phase: String(data.phase ?? ""),
+      initiative: String(data.initiative ?? data.source_initiative ?? "")
     };
   } catch {
     return null;
@@ -4428,6 +4562,52 @@ 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";
 function first(values) {
@@ -4515,15 +4695,27 @@ function buildProjectExplanation(dir) {
     id: a.id || a.title,
     title: a.title,
     status: a.status,
+    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
+    initiative: a.initiative,
     knowledgeLevel: a.knowledgeLevel,
     hasOwnership: a.codeGlobs.length > 0,
     domains: a.domains
   }));
+  const byState = lifecycleCounts(items.map((i) => i.lifecycle));
+  const initiativeMap = /* @__PURE__ */ new Map();
+  for (const i of items) {
+    const name = i.initiative || "Unassigned";
+    if (!initiativeMap.has(name)) initiativeMap.set(name, emptyLifecycleCounts());
+    initiativeMap.get(name)[i.lifecycle]++;
+  }
+  const initiatives = [...initiativeMap.entries()].map(([name, states]) => ({ name, states })).sort((a, b) => a.name.localeCompare(b.name));
   const workItems = {
     total: items.length,
-    inProgress: items.filter((i) => i.status === "in-progress").length,
+    inProgress: items.filter((i) => i.lifecycle === "in-progress").length,
     done: items.filter((i) => i.status === "done").length,
     cancelled: items.filter((i) => i.status === "cancelled").length,
+    byState,
+    initiatives,
     items
   };
   const withOwnership = items.filter((i) => i.hasOwnership).length;
@@ -4533,6 +4725,9 @@ 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 roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
+  const roadmap = roadmapStats(roadmapMd, items.length);
   const mappedModules = loadMappedModules(dir);
   const missingKnowledge = [];
   if (!knowledge.hasScan) missingKnowledge.push("Scan baseline (.kaddo/scan.json)");
@@ -4560,8 +4755,12 @@ function buildProjectExplanation(dir) {
   }
   if (!knowledge.hasRoadmap) {
     suggestedNextSteps.push("Use roadmap-agent to generate knowledge/delivery/roadmap.md.");
+  } else if (roadmap.remaining > 0) {
+    suggestedNextSteps.push(
+      `Materialize ${roadmap.remaining} roadmap candidate(s) with \`kaddo create --from roadmap\`.`
+    );
   }
-  if (items.length === 0) {
+  if (items.length === 0 && !roadmap.present) {
     suggestedNextSteps.push("Create your first Work Item with `kaddo create`.");
   } else if (ownership.workItemsMissingOwnership > 0) {
     suggestedNextSteps.push(
@@ -4576,6 +4775,7 @@ function buildProjectExplanation(dir) {
     ownership,
     domains,
     layers,
+    roadmap,
     mappedModules,
     missingKnowledge,
     suggestedNextSteps
@@ -4584,6 +4784,14 @@ function buildProjectExplanation(dir) {
 function stateLabel(state) {
   return state === "pre-ai" ? "pre-ai" : state;
 }
+var LIFECYCLE_LABEL = {
+  draft: "Draft",
+  ready: "Ready",
+  "in-progress": "In Progress",
+  blocked: "Blocked",
+  completed: "Completed",
+  archived: "Archived"
+};
 function renderExplanationHuman(exp) {
   const lines = [];
   lines.push("# Project Explanation");
@@ -4619,14 +4827,41 @@ function renderExplanationHuman(exp) {
   lines.push(`- Tech: ${ls("Tech")}`);
   lines.push(`- Delivery: ${ls("Delivery")}`);
   lines.push(`- Agents: ${exp.knowledge.hasAgents ? "available" : "missing"}`);
-  lines.push(`- Work items: ${exp.workItems.total}`);
+  if (exp.roadmap.present) {
+    lines.push(`- Roadmap candidates: ${exp.roadmap.candidates}`);
+    lines.push(`- Materialized work items: ${exp.roadmap.materialized}`);
+    if (exp.roadmap.remaining > 0)
+      lines.push(`- Remaining candidates: ${exp.roadmap.remaining}`);
+  } else {
+    lines.push(`- Work items: ${exp.workItems.total}`);
+  }
   lines.push(
     `- Ownership coverage: ${exp.ownership.workItemsWithOwnership}/${exp.ownership.workItemsTotal} work items`
   );
   lines.push("");
-  const active = exp.workItems.items.filter((i) => i.status === "in-progress");
+  if (exp.workItems.total > 0) {
+    lines.push("## Work Items");
+    for (const s of LIFECYCLE_STATES) {
+      lines.push(`- ${LIFECYCLE_LABEL[s]}: ${exp.workItems.byState[s]}`);
+    }
+    lines.push("");
+    const grouped = exp.workItems.initiatives.filter(
+      (g) => LIFECYCLE_STATES.some((s) => g.states[s] > 0)
+    );
+    if (grouped.length > 0) {
+      lines.push("## Work Items by Initiative");
+      for (const g of grouped) {
+        const parts = LIFECYCLE_STATES.filter((s) => g.states[s] > 0).map(
+          (s) => `${LIFECYCLE_LABEL[s]}: ${g.states[s]}`
+        );
+        lines.push(`- ${g.name} \u2014 ${parts.join(" \xB7 ")}`);
+      }
+      lines.push("");
+    }
+  }
+  const active = exp.workItems.items.filter((i) => i.lifecycle === "in-progress");
   if (active.length > 0) {
-    lines.push("## Active Work Items");
+    lines.push("## In Progress");
     for (const wi of active) {
       const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
       const owned = wi.hasOwnership ? " \u25CF" : " \u25CB";
@@ -4938,6 +5173,7 @@ function toContextWorkItem(a) {
     type: a.type,
     title: a.title,
     status: a.status,
+    lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
     knowledgeLevel: a.knowledgeLevel,
     domains: a.domains
   };
@@ -4945,6 +5181,9 @@ function toContextWorkItem(a) {
 function toContextArtifact(a) {
   return { id: a.id, type: a.type, title: a.title, summary: a.summary, codeGlobs: a.codeGlobs };
 }
+function isDeliveryWorkItem(a) {
+  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
+}
 function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   const missing = [];
   const scanJson = readScanJson(dir);
@@ -4967,12 +5206,17 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   const archPath = join(dir, ARCH_DIR5);
   const allArtifacts = exists(archPath) ? readArtifacts(archPath) : [];
   const workItems = allArtifacts.filter(
-    (a) => a.type && a.type !== "current-state" && a.type !== "roadmap"
+    (a) => isDeliveryWorkItem(a) && isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))
   );
   if (workItems.length === 0) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
+  const roadmapPath = join(dir, ARCH_DIR5, "delivery", "roadmap.md");
+  const materialized = allArtifacts.filter(
+    (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
+  ).length;
+  const roadmap = roadmapStats(exists(roadmapPath) ? readFile(roadmapPath) : null, materialized);
   const mappedModules = loadMappedModules(dir);
   const layers = knowledgeLayers(dir);
   return {
@@ -4999,9 +5243,10 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       roadmapSummary,
       inventoryAvailable,
       workItems: workItems.map(toContextWorkItem),
-      artifacts: workItems.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
+      artifacts: allArtifacts.filter((a) => a.codeGlobs.length > 0).map(toContextArtifact)
     },
     layers,
+    roadmap,
     mappedModules,
     missing,
     handoff: {
@@ -5076,18 +5321,32 @@ function renderContextPack(pack) {
   parts.push("## Current Knowledge\n");
   parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
   parts.push("## Roadmap\n");
+  if (pack.roadmap.present) {
+    parts.push(
+      [
+        `- Roadmap candidates: ${pack.roadmap.candidates}`,
+        `- Materialized work items: ${pack.roadmap.materialized}`,
+        `- Remaining candidates: ${pack.roadmap.remaining}`
+      ].join("\n") + "\n"
+    );
+    if (pack.roadmap.remaining > 0) {
+      parts.push(
+        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+      );
+    }
+  }
   parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
-  parts.push("## Existing Work Items\n");
+  parts.push("## Active Work Items\n");
   if (knowledge.workItems.length > 0) {
     const lines = knowledge.workItems.map((wi) => {
       const level = wi.knowledgeLevel ? ` [${wi.knowledgeLevel}]` : "";
-      const status = wi.status ? ` (${wi.status})` : "";
+      const status = wi.lifecycle ? ` (${wi.lifecycle})` : wi.status ? ` (${wi.status})` : "";
       const domains = wi.domains.length > 0 ? ` \xB7 domains: ${wi.domains.join(", ")}` : "";
       return `- ${wi.id || wi.title} [${wi.type}]${level}${status} \u2014 ${wi.title}${domains}`;
     });
     parts.push(lines.join("\n") + "\n");
   } else {
-    parts.push("No work items found.\n");
+    parts.push("No active work items found.\n");
   }
   parts.push("## Artifacts and Ownership\n");
   if (knowledge.artifacts.length > 0) {
@@ -5339,7 +5598,9 @@ function toActive(a) {
 function activeWorkItems(dir) {
   const archDir = join(dir, "knowledge");
   if (!exists(archDir)) return [];
-  return readArtifacts(archDir).filter((a) => isWorkItem(a) && a.status === "in-progress").map(toActive);
+  return readArtifacts(archDir).filter(
+    (a) => isWorkItem(a) && lifecycleStateOf({ status: a.status, filePath: a.filePath }) === "in-progress"
+  ).map(toActive);
 }
 function branchPrefix(type) {
   switch (type) {
@@ -5439,8 +5700,11 @@ function runUnderstand() {
     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 Work Item candidates that are not materialized yet.");
+    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/.");
   }
@@ -5454,6 +5718,24 @@ function runUnderstand() {
   if (groupAgents.length > 0) {
     console.log(`Agents for this phase: ${groupAgents.join(", ")}`);
   }
+  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.");
+    }
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");
@@ -6371,11 +6653,12 @@ var WORK_ITEM = `---
 type: feature
 id: WI-001
 title: "Short, action-oriented title"
-status: in-progress
+status: draft
 knowledge_level: K2
 source: manual
 source_id:
-source_initiative:
+phase: now
+initiative:
 domains: []
 capabilities: []
 code: []
@@ -6406,6 +6689,14 @@ _Optional. Key decisions or approach. Keep it minimal at low knowledge levels._
 
 _Optional. What could go wrong?_
 
+## Out of scope
+
+_What is intentionally not included in this Work Item?_
+
+## Validation
+
+_How will this be validated?_
+
 ## Definition of Done
 
 - [ ] Code merged
@@ -8145,7 +8436,7 @@ async function runBootstrap(dir = cwd()) {
 
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.5.1");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.6.0");
 program.command("init").description("Initialize Kaddo in the current project").action(async () => {
   await runInit();
 });

package/package.json

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