@kaddo/cli 3.6.0 → 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
 
@@ -3182,6 +3191,7 @@ function roadmapStats(markdown, 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;
@@ -3200,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);
@@ -3222,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}`,
@@ -3274,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
 
@@ -3298,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}`,
@@ -3330,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._
@@ -3379,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}
@@ -3390,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.`);
 }
@@ -3419,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.`);
 }
@@ -3444,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}`,
@@ -3525,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
@@ -3607,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.`);
@@ -3676,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;
@@ -4511,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) {
@@ -4598,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;
@@ -4675,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");
@@ -4722,9 +4839,29 @@ function renderExplanationHuman(exp) {
     `- 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";
@@ -5036,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
   };
@@ -5043,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);
@@ -5065,7 +5206,7 @@ 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.");
@@ -5102,7 +5243,7 @@ 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,
@@ -5195,17 +5336,17 @@ function renderContextPack(pack) {
     }
   }
   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) {
@@ -5457,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) {
@@ -5575,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("");
@@ -6492,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: []
@@ -6527,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

package/package.json

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