@kaddo/cli 3.43.0 → 3.45.0

package/README.md

@@ -542,6 +542,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.41 | Tech knowledge structure: `knowledge/tech/discovery/` for architecture-notes/decision-candidates (core vs decisions vs discovery); `kaddo adr` reads discovery-first with legacy fallback; `kaddo tech organize` migrates safely; `explain` shows `## Tech Knowledge` |
 | v3.42 | Agent & skill version metadata: installed agents/skills carry a `version:`; `kaddo agents status` / `kaddo skills status` classify up-to-date/outdated/unknown-version/modified/missing; `agents update` / `skills update` refresh outdated safely (never overwrite edits without `--force`); MCP `kaddo://installed-assets` |
 | v3.43 | Capability-grounded roadmap: each `RM-xxx` candidate is graded on related domain / capability / source signals; `roadmap_quality` surfaced in `explain`/`context`/`understand`; `create --from roadmap` preserves `source_roadmap_candidate` + related metadata into the Work Item; roadmap-agent emits grounded fields (never materializes Work Items); MCP `kaddo://roadmap-quality` |
+| v3.44 | Roadmap counting alignment + materialization quality: `explain`/`context` separate **Roadmap initiatives** from **Work Item candidates** (`## Roadmap Status`); two-level `roadmapQuality` (initiatives + work_item_candidates); `create --from roadmap` normalizes metadata — fills `domains` from `related_domain`, splits comma-joined `related_capabilities` into a real list, carries `source_roadmap_initiative`/`source_work_item_candidate`/`source_signals`/`decision_candidates`, improved Source + Context-From-Roadmap body + ADR warning; MCP `kaddo://work-item-candidates` |
+| v3.45 | State-aware next step: `resolveNextStep` decides from the real delivery state (draft/ready/in-progress, ownership, ADRs, adapters) instead of always suggesting `create --from roadmap` — draft → work-item-agent, ready → adapter/implementation-agent, in-progress → guard; parallel **secondary** recommendations (ownership, ADRs, remaining candidates); `deliveryState` + recommendation in `explain`/`context`; MCP `kaddo://next-step` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -3032,13 +3032,22 @@ that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and
 without surfacing it. -->
 \`\`\`
 
-### Preserve roadmap metadata (VS-077)
+### Preserve roadmap metadata (VS-077 / VS-078)
 
-When a Work Item comes from \`kaddo create --from roadmap\`, the front matter already carries
-\`source_roadmap_candidate\`, \`related_domain\`, \`related_capability\` (+ \`related_capabilities\`),
-\`knowledge_level\`, \`expected_value\`, \`risks\` and \`dependencies\`. **Keep and refine** this metadata \u2014
-do not drop the trace back to the capability domain and source signals. Add \`related_decisions\` /
-\`decision_candidates\` when the work depends on a technical decision.
+When a Work Item comes from \`kaddo create --from roadmap\`, the front matter already carries the trace
+back to the roadmap. **Keep and refine \u2014 never delete** these fields:
+
+- \`source_roadmap_initiative\` and \`source_work_item_candidate\` (the RM-xxx initiative and the
+  WI-CANDIDATE-xxx it was materialized from)
+- \`related_domain\` and \`domains\` (keep them consistent \u2014 \`domains\` must not be empty when
+  \`related_domain\` exists)
+- \`related_capabilities\` (a real list, one capability per item \u2014 never a single comma-joined string)
+- \`expected_value\`, \`risks\`, \`dependencies\`
+- \`source_signals\` (do **not** invent them \u2014 if absent, leave them absent)
+- \`decision_candidates\` and \`related_decisions\` (when the work depends on a technical decision)
+
+Do not drop the trace back to the capability domain and source signals. If a Work Item depends on a
+tech decision candidate with no ADR yet, keep the warning surfaced in the body.
 
 ## Where to Save the Result
 
@@ -4530,7 +4539,12 @@ function splitInitiatives(markdown) {
   return blocks;
 }
 function parseBlock(block) {
-  const meta = { relatedCapabilities: [], dependencies: [], openQuestions: [] };
+  const meta = {
+    relatedCapabilities: [],
+    dependencies: [],
+    openQuestions: [],
+    sourceSignals: []
+  };
   const rawCandidates = [];
   let listField = null;
   let inCandidateSection = false;
@@ -4580,7 +4594,7 @@ function parseBlock(block) {
         meta.impact = value || void 0;
       } else if (key === "risk") {
         meta.risk = value || void 0;
-      } else if (key === "project area / domain" || key === "domain" || key === "project area") {
+      } else if (key === "project area / domain" || key === "domain" || key === "project area" || key === "related domain") {
         meta.domain = value || void 0;
       } else if (key === "related capabilities") {
         listField = "relatedCapabilities";
@@ -4591,6 +4605,9 @@ function parseBlock(block) {
       } else if (key === "open questions") {
         listField = "openQuestions";
         if (value) meta.openQuestions.push(value);
+      } else if (key === "source signals" || key === "source signal") {
+        listField = "sourceSignals";
+        if (value) meta.sourceSignals.push(value);
       }
       continue;
     }
@@ -4608,6 +4625,7 @@ function parseBlock(block) {
     }
   }
   flush();
+  const decisionCandidates = decisionCandidatesFromSignals(meta.sourceSignals);
   return rawCandidates.map((c) => ({
     ...c,
     initiative: block.initiative.id || block.initiative.title ? { ...block.initiative } : void 0,
@@ -4616,9 +4634,23 @@ function parseBlock(block) {
     impact: meta.impact,
     risk: meta.risk,
     dependencies: meta.dependencies.length ? [...meta.dependencies] : void 0,
-    openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0
+    openQuestions: meta.openQuestions.length ? [...meta.openQuestions] : void 0,
+    sourceSignals: meta.sourceSignals.length ? [...meta.sourceSignals] : void 0,
+    decisionCandidates: decisionCandidates.length ? decisionCandidates : void 0
   }));
 }
+function decisionCandidatesFromSignals(signals) {
+  const out = [];
+  for (const sig of signals) {
+    const m = sig.match(/decision candidate\s*:?\s*(.+)$/i);
+    if (!m) continue;
+    const rest = m[1].trim();
+    const token = rest.match(/\b[A-Z][A-Z0-9_]{2,}\b/);
+    const value = token ? token[0] : rest.replace(/[.。]+$/, "").trim();
+    if (value && !out.includes(value)) out.push(value);
+  }
+  return out;
+}
 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*(.*)$/;
@@ -4700,10 +4732,51 @@ function parseRoadmapCandidates(markdown) {
   if (strict.length > 0) return strict;
   return parseFlexible(markdown);
 }
+function countRoadmapInitiatives(markdown) {
+  if (markdown == null) return 0;
+  let n = 0;
+  for (const line of markdown.split(/\r?\n/)) if (INITIATIVE_RE.test(line)) n++;
+  return n;
+}
 function roadmapStats(markdown, materialized) {
-  if (markdown == null) return { present: false, candidates: 0, materialized, remaining: 0 };
+  if (markdown == null)
+    return {
+      present: false,
+      initiatives: 0,
+      work_item_candidates: 0,
+      materialized_work_items: materialized,
+      remaining_work_item_candidates: 0,
+      candidates: 0,
+      materialized,
+      remaining: 0
+    };
   const candidates = parseRoadmapCandidates(markdown).length;
-  return { present: true, candidates, materialized, remaining: Math.max(0, candidates - materialized) };
+  const remaining = Math.max(0, candidates - materialized);
+  return {
+    present: true,
+    initiatives: countRoadmapInitiatives(markdown),
+    work_item_candidates: candidates,
+    materialized_work_items: materialized,
+    remaining_work_item_candidates: remaining,
+    candidates,
+    materialized,
+    remaining
+  };
+}
+function normalizeCapabilityList(raw) {
+  if (!raw || raw.length === 0) return [];
+  const out = [];
+  for (const entry of raw) {
+    for (const part of entry.split(/[,;]/)) {
+      const cap = part.replace(/[.。]+\s*$/, "").trim();
+      if (cap && !out.includes(cap)) out.push(cap);
+    }
+  }
+  return out;
+}
+function domainsFromRelated(domain) {
+  const d = domain?.trim();
+  return d ? [d] : [];
 }
 
 // src/commands/create.ts
@@ -4999,32 +5072,44 @@ function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
   const today2 = (/* @__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 q = (s) => s.replace(/"/g, "'");
+  const domains = domainsFromRelated(candidate.domain);
+  const relatedCapabilities = normalizeCapabilityList(candidate.relatedCapabilities);
+  const risks = candidate.risk ? [candidate.risk] : [];
+  const dependencies = candidate.dependencies ?? [];
+  const sourceSignals = candidate.sourceSignals ?? [];
+  const decisionCandidates = candidate.decisionCandidates ?? [];
+  const yamlList2 = (key, items) => items.length === 0 ? [] : [`${key}:`, ...items.map((i) => `  - "${q(i)}"`)];
   const lines = [
     "---",
     `type: ${type}`,
     `id: ${id}`,
-    `title: "${title}"`,
+    `title: "${q(title)}"`,
     `knowledge_level: ${level}`,
     `status: draft`,
     `phase: now`,
-    `initiative: "${initiative.replace(/"/g, "'")}"`,
-    `domains: []`,
+    `initiative: "${q(initiative)}"`,
+    ...yamlList2("domains", domains),
+    ...domains.length === 0 ? ["domains: []"] : [],
     `code: []`,
     `created_at: ${today2}`,
     `source: roadmap`,
     `source_id: ${candidate.id}`,
     `source_initiative: ${candidate.initiative?.id ?? "unknown"}`,
-    // Capability-grounded traceability (VS-077): carry the roadmap metadata into the Work Item.
-    `source_roadmap_candidate: ${candidate.initiative?.id ?? candidate.id}`,
-    ...candidate.domain ? [`related_domain: "${candidate.domain.replace(/"/g, "'")}"`] : [],
-    ...candidate.relatedCapabilities && candidate.relatedCapabilities.length > 0 ? [
-      `related_capability: "${candidate.relatedCapabilities[0].replace(/"/g, "'")}"`,
-      `related_capabilities: [${candidate.relatedCapabilities.map((c) => `"${c.replace(/"/g, "'")}"`).join(", ")}]`
-    ] : [],
-    ...candidate.expectedValue ? [`expected_value: "${candidate.expectedValue.replace(/"/g, "'")}"`] : [],
-    ...candidate.risk ? [`risks: "${candidate.risk.replace(/"/g, "'")}"`] : [],
-    ...candidate.dependencies && candidate.dependencies.length > 0 ? [`dependencies: [${candidate.dependencies.map((d) => `"${d.replace(/"/g, "'")}"`).join(", ")}]`] : [],
-    `summary: "${summary.replace(/"/g, "'")}"`,
+    // Capability-grounded traceability (VS-077 / VS-078): distinguish the parent roadmap initiative
+    // from the specific Work Item candidate it was materialized from.
+    `source_roadmap_initiative: ${candidate.initiative?.id ?? "unknown"}`,
+    `source_work_item_candidate: ${candidate.id}`,
+    ...candidate.initiative?.title ? [`source_initiative_title: "${q(candidate.initiative.title)}"`] : [],
+    ...candidate.domain ? [`related_domain: "${q(candidate.domain)}"`] : [],
+    ...yamlList2("related_capabilities", relatedCapabilities),
+    ...candidate.expectedValue ? [`expected_value: "${q(candidate.expectedValue)}"`] : [],
+    ...yamlList2("risks", risks),
+    ...yamlList2("dependencies", dependencies),
+    ...yamlList2("source_signals", sourceSignals),
+    ...yamlList2("decision_candidates", decisionCandidates),
+    ...decisionCandidates.length > 0 ? ["related_decisions: []"] : [],
+    `summary: "${q(summary)}"`,
     "---"
   ];
   return lines.join("\n");
@@ -5036,14 +5121,24 @@ function buildRoadmapBody(type, level, title, candidate, answers, qualityGate) {
   sections.push(`> Type: ${type} \xB7 Level: ${level}
 `);
   const initiativeLabel = candidate.initiative ? `${candidate.initiative.id ?? ""}${candidate.initiative.title ? ` \u2014 ${candidate.initiative.title}` : ""}`.trim() : "unknown";
-  sections.push(
-    [
-      "## Source\n",
-      `- Source: roadmap`,
-      `- Candidate: ${candidate.id}`,
-      `- Initiative: ${initiativeLabel || "unknown"}`
-    ].join("\n") + "\n"
-  );
+  const relatedCapabilities = normalizeCapabilityList(candidate.relatedCapabilities);
+  const sourceLines = [
+    "## Source\n",
+    `- Source: roadmap`,
+    `- Roadmap Initiative: ${initiativeLabel || "unknown"}`,
+    `- Work Item Candidate: ${candidate.id}`
+  ];
+  if (candidate.domain) sourceLines.push(`- Related domain: ${candidate.domain}`);
+  if (relatedCapabilities.length) {
+    sourceLines.push("- Related capabilities:");
+    relatedCapabilities.forEach((c) => sourceLines.push(`  - ${c}`));
+  }
+  sections.push(sourceLines.join("\n") + "\n");
+  if (candidate.decisionCandidates?.length) {
+    sections.push(
+      "> Warning: This Work Item is related to technical decision candidates that have not been materialized as ADRs.\n"
+    );
+  }
   if (answers.problem) sections.push(`## Problem
 
 ${answers.problem}
@@ -5053,22 +5148,22 @@ ${answers.problem}
 
 ${expectedValue}
 `);
-  const ctx = [];
-  if (candidate.relatedCapabilities?.length)
-    ctx.push(`**Related capabilities:** ${candidate.relatedCapabilities.join(", ")}`);
-  if (candidate.domain) ctx.push(`**Domain:** ${candidate.domain}`);
-  if (candidate.impact) ctx.push(`**Impact:** ${candidate.impact}`);
-  if (candidate.risk) ctx.push(`**Risk:** ${candidate.risk}`);
+  const initiativeRef = candidate.initiative?.id ? `roadmap initiative ${candidate.initiative.id}` : "a roadmap candidate";
+  const ctx = [`This Work Item was materialized from ${initiativeRef}.`, ""];
+  if (candidate.expectedValue) ctx.push(`**Expected value:** ${candidate.expectedValue}`);
+  if (candidate.risk) ctx.push(`**Risks:** ${candidate.risk}`);
   if (candidate.dependencies?.length)
-    ctx.push(`**Dependencies:**
-${formatList(candidate.dependencies)}`);
-  const initiativeNote = candidate.initiative?.id ? `This candidate was created from the roadmap initiative ${candidate.initiative.id}.` : "This work item was created from a roadmap candidate.";
-  sections.push(
-    `## Context From Roadmap
+    ctx.push(`**Dependencies:** ${candidate.dependencies.join("; ")}`);
+  if (candidate.sourceSignals?.length) {
+    ctx.push(`**Source signals:**
+${formatList(candidate.sourceSignals)}`);
+  } else {
+    ctx.push("**Source signals:** _Not provided in roadmap._");
+  }
+  sections.push(`## Context From Roadmap
 
-${initiativeNote}${ctx.length ? "\n\n" + ctx.join("\n\n") : ""}
-`
-  );
+${ctx.join("\n\n")}
+`);
   if (answers.acceptance_criteria) {
     const items = answers.acceptance_criteria.split("\n").map((l) => l.trim()).filter(Boolean);
     sections.push(`## Acceptance Criteria
@@ -8018,7 +8113,124 @@ function buildSharedFileStatuses(statuses) {
   }));
 }
 
+// src/core/decisions.ts
+var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
+var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
+var DECISIONS_DIR = "knowledge/tech/decisions";
+function resolveCandidatesPath(dir) {
+  const discovery = exists(join(dir, CANDIDATES_DISCOVERY));
+  const legacy = exists(join(dir, CANDIDATES_LEGACY));
+  if (discovery) return { path: CANDIDATES_DISCOVERY, legacy: false, bothExist: legacy };
+  if (legacy) return { path: CANDIDATES_LEGACY, legacy: true, bothExist: false };
+  return { path: null, legacy: false, bothExist: false };
+}
+function cleanCandidateTitle(title) {
+  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
+}
+function slugify2(s) {
+  return cleanCandidateTitle(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
+}
+function parseDecisionCandidates(md) {
+  const out = [];
+  for (const line of md.split(/\r?\n/)) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      const raw = m[1].trim();
+      if (!raw || /^_.*_$/.test(raw)) continue;
+      const t = cleanCandidateTitle(raw);
+      if (t) out.push(t);
+    }
+  }
+  return out;
+}
+function countAdrs(dir) {
+  const base = join(dir, DECISIONS_DIR);
+  if (!exists(base)) return { total: 0, draft: 0, accepted: 0 };
+  let total = 0;
+  let draft = 0;
+  let accepted = 0;
+  for (const entry of readDir(base)) {
+    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
+    const full = join(base, entry);
+    if (!isFile(full)) continue;
+    total += 1;
+    let content = "";
+    try {
+      content = readFile(full);
+    } catch {
+      continue;
+    }
+    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
+    if (status === "accepted") accepted += 1;
+    else draft += 1;
+  }
+  return { total, draft, accepted };
+}
+function buildTechDecisions(dir) {
+  const resolved = resolveCandidatesPath(dir);
+  let titles = [];
+  if (resolved.path) {
+    try {
+      titles = parseDecisionCandidates(readFile(join(dir, resolved.path)));
+    } catch {
+      titles = [];
+    }
+  }
+  const { total, draft, accepted } = countAdrs(dir);
+  const candidate_list = titles.map((title, i) => {
+    const n = String(total + i + 1).padStart(3, "0");
+    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
+  });
+  let status;
+  if (accepted > 0) status = "accepted-adrs";
+  else if (total > 0) status = "draft-adrs";
+  else if (titles.length > 0) status = "candidates";
+  else status = "none";
+  return {
+    status,
+    candidates: titles.length,
+    adrs: total,
+    draft_adrs: draft,
+    accepted_adrs: accepted,
+    candidate_list,
+    candidates_source: resolved.path,
+    candidates_legacy_location: resolved.legacy,
+    candidates_both_exist: resolved.bothExist
+  };
+}
+
 // src/core/next-step.ts
+function buildDeliveryState(dir) {
+  const wis = discoverWorkItems(dir);
+  const byState = (s) => wis.filter((w) => w.lifecycle === s).length;
+  const total = wis.length;
+  const withOwnership = wis.filter((w) => w.codeGlobs.length > 0).length;
+  const td = buildTechDecisions(dir);
+  const roadmapPath = join(dir, "knowledge/delivery/roadmap.md");
+  const roadmapMd = exists(roadmapPath) ? safeRead(roadmapPath) : null;
+  const stats = roadmapStats(roadmapMd, total);
+  const adapters = installedAdapters(dir);
+  return {
+    phase: "",
+    draft_work_items: byState("draft"),
+    ready_work_items: byState("ready"),
+    in_progress_work_items: byState("in-progress"),
+    blocked_work_items: byState("blocked"),
+    total_work_items: total,
+    ownership_coverage: `${withOwnership}/${total}`,
+    remaining_work_item_candidates: stats.remaining_work_item_candidates,
+    decision_candidates: td.candidates,
+    accepted_adrs: td.accepted_adrs,
+    adapters_installed: adapters.length
+  };
+}
+function safeRead(p2) {
+  try {
+    return readFile(p2);
+  } catch {
+    return null;
+  }
+}
 function roadmapSignal(dir) {
   const p2 = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p2)) return "missing";
@@ -8115,15 +8327,117 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (roadmap !== "has-candidates") {
     return { id: "roadmap", phase: "Planning", label: "Use roadmap-agent to define roadmap candidates (`kaddo roadmap`).", command: "kaddo roadmap", agent: "roadmap-agent", target: "knowledge/delivery/roadmap.md", reason: "The roadmap has no candidates yet." };
   }
-  const wi = workItemsSignal(dir);
-  if (wi === "none" || wi === "none-ready") {
-    return { id: "create-work-item", phase: "Delivery Preparation", label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap", reason: "The roadmap has candidates but no Work Item is ready." };
+  const st = buildDeliveryState(dir);
+  const secondary = buildSecondaryRecommendations(st);
+  if (st.total_work_items === 0) {
+    return {
+      id: "create-work-item",
+      phase: "Delivery Preparation",
+      label: "Run `kaddo create --from roadmap` to materialize the first Work Item.",
+      command: "kaddo create --from roadmap",
+      reason: "The roadmap has candidates but no Work Item exists yet.",
+      ...secondary.length ? { secondary } : {}
+    };
   }
-  const adapters = installedAdapters(dir);
-  if (adapters.length === 0) {
-    return { id: "install-adapter", phase: "Active Delivery", label: "Run `kaddo adapters list` and install the adapter for your preferred agent.", command: "kaddo adapters list", reason: "A Work Item is ready but no adapter is installed." };
+  const adapters = st.adapters_installed;
+  if (st.ready_work_items > 0) {
+    if (adapters === 0) {
+      return {
+        id: "install-adapter",
+        phase: "Active Delivery",
+        label: "Install or configure an adapter before implementation (`kaddo adapters list`).",
+        command: "kaddo adapters list",
+        reason: `${st.ready_work_items} Work Item(s) are ready but no adapter is installed.`,
+        ...secondary.length ? { secondary } : {}
+      };
+    }
+    return {
+      id: "implement",
+      phase: "Active Delivery",
+      label: "Use the implementation-agent or your installed adapter to plan implementation.",
+      agent: "implementation-agent",
+      reason: `${st.ready_work_items} Work Item(s) are ready and an adapter is installed.`,
+      ...secondary.length ? { secondary } : {}
+    };
   }
-  return { id: "implement", phase: "Active Delivery", label: "Implement the ready Work Item and run `kaddo guard`.", reason: "A Work Item is ready and an adapter is installed." };
+  if (st.in_progress_work_items > 0) {
+    return {
+      id: "guard",
+      phase: "Active Delivery",
+      label: "Run `kaddo guard` and update affected knowledge after significant changes.",
+      command: "kaddo guard",
+      reason: `${st.in_progress_work_items} Work Item(s) are in progress.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.draft_work_items > 0) {
+    return {
+      id: "refine-work-item",
+      phase: "Active Delivery",
+      label: "Refine the existing draft Work Item with the work-item-agent.",
+      agent: "work-item-agent",
+      skill: "work-item-refinement",
+      reason: `There ${st.draft_work_items === 1 ? "is" : "are"} ${st.draft_work_items} draft Work Item${st.draft_work_items === 1 ? "" : "s"} and no Work Item is ready.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.blocked_work_items > 0) {
+    return {
+      id: "resolve-blocker",
+      phase: "Active Delivery",
+      label: "Resolve the blocker on the blocked Work Item with the work-item-agent.",
+      agent: "work-item-agent",
+      reason: `${st.blocked_work_items} Work Item(s) are blocked.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.remaining_work_item_candidates > 0) {
+    return {
+      id: "materialize-more-work-items",
+      phase: "Maintenance",
+      label: `Materialize the remaining ${st.remaining_work_item_candidates} Work Item candidate(s) with \`kaddo create --from roadmap\`.`,
+      command: "kaddo create --from roadmap",
+      reason: "No active Work Items remain; roadmap candidates are still pending.",
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  return {
+    id: "plan-next",
+    phase: "Maintenance",
+    label: "Use the roadmap-agent to plan the next initiative.",
+    agent: "roadmap-agent",
+    reason: "No active Work Items and no remaining roadmap candidates."
+  };
+}
+function buildSecondaryRecommendations(st) {
+  const out = [];
+  const [withOwnership] = st.ownership_coverage.split("/").map(Number);
+  if (st.total_work_items > 0 && withOwnership < st.total_work_items) {
+    out.push({
+      id: "suggest-ownership",
+      label: "Run `kaddo owners suggest` for Work Items without code ownership.",
+      command: "kaddo owners suggest",
+      reason: `Ownership coverage is ${st.ownership_coverage}.`
+    });
+  }
+  if (st.total_work_items > 0 && st.decision_candidates > 0 && st.accepted_adrs === 0) {
+    out.push({
+      id: "materialize-adrs",
+      label: "Use the adr-writing skill (`kaddo adr`) to materialize decision candidates into ADRs before implementing related technical Work Items.",
+      command: "kaddo adr",
+      skill: "adr-writing",
+      reason: `There are ${st.decision_candidates} technical decision candidate(s) and ${st.accepted_adrs} accepted ADR(s).`
+    });
+  }
+  if (st.total_work_items > 0 && st.remaining_work_item_candidates > 0) {
+    out.push({
+      id: "materialize-more-work-items",
+      label: `Later, materialize the remaining ${st.remaining_work_item_candidates} Work Item candidate(s) with \`kaddo create --from roadmap\`.`,
+      command: "kaddo create --from roadmap",
+      reason: `There are ${st.remaining_work_item_candidates} remaining Work Item candidate(s).`
+    });
+  }
+  return out;
 }
 
 // src/core/readiness.ts
@@ -8218,92 +8532,6 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   };
 }
 
-// src/core/decisions.ts
-var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
-var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
-var DECISIONS_DIR = "knowledge/tech/decisions";
-function resolveCandidatesPath(dir) {
-  const discovery = exists(join(dir, CANDIDATES_DISCOVERY));
-  const legacy = exists(join(dir, CANDIDATES_LEGACY));
-  if (discovery) return { path: CANDIDATES_DISCOVERY, legacy: false, bothExist: legacy };
-  if (legacy) return { path: CANDIDATES_LEGACY, legacy: true, bothExist: false };
-  return { path: null, legacy: false, bothExist: false };
-}
-function cleanCandidateTitle(title) {
-  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
-}
-function slugify2(s) {
-  return cleanCandidateTitle(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
-}
-function parseDecisionCandidates(md) {
-  const out = [];
-  for (const line of md.split(/\r?\n/)) {
-    const m = line.match(/^##\s+(.+?)\s*$/);
-    if (m) {
-      const raw = m[1].trim();
-      if (!raw || /^_.*_$/.test(raw)) continue;
-      const t = cleanCandidateTitle(raw);
-      if (t) out.push(t);
-    }
-  }
-  return out;
-}
-function countAdrs(dir) {
-  const base = join(dir, DECISIONS_DIR);
-  if (!exists(base)) return { total: 0, draft: 0, accepted: 0 };
-  let total = 0;
-  let draft = 0;
-  let accepted = 0;
-  for (const entry of readDir(base)) {
-    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
-    const full = join(base, entry);
-    if (!isFile(full)) continue;
-    total += 1;
-    let content = "";
-    try {
-      content = readFile(full);
-    } catch {
-      continue;
-    }
-    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
-    if (status === "accepted") accepted += 1;
-    else draft += 1;
-  }
-  return { total, draft, accepted };
-}
-function buildTechDecisions(dir) {
-  const resolved = resolveCandidatesPath(dir);
-  let titles = [];
-  if (resolved.path) {
-    try {
-      titles = parseDecisionCandidates(readFile(join(dir, resolved.path)));
-    } catch {
-      titles = [];
-    }
-  }
-  const { total, draft, accepted } = countAdrs(dir);
-  const candidate_list = titles.map((title, i) => {
-    const n = String(total + i + 1).padStart(3, "0");
-    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
-  });
-  let status;
-  if (accepted > 0) status = "accepted-adrs";
-  else if (total > 0) status = "draft-adrs";
-  else if (titles.length > 0) status = "candidates";
-  else status = "none";
-  return {
-    status,
-    candidates: titles.length,
-    adrs: total,
-    draft_adrs: draft,
-    accepted_adrs: accepted,
-    candidate_list,
-    candidates_source: resolved.path,
-    candidates_legacy_location: resolved.legacy,
-    candidates_both_exist: resolved.bothExist
-  };
-}
-
 // src/core/assets.ts
 import matter4 from "gray-matter";
 function canonicalAgents() {
@@ -8431,16 +8659,25 @@ function buildRoadmapQuality(dir) {
   const items = parseRoadmapCandidateQuality(md);
   const count = (pred) => items.filter(pred).length;
   const grounded = count((i) => i.grounded);
-  return {
-    candidates: items.length,
+  const initiatives = {
+    total: items.length,
     grounded,
     with_related_domain: count((i) => i.hasRelatedDomain),
     with_related_capability: count((i) => i.hasRelatedCapability),
     with_source_signals: count((i) => i.hasSourceSignals),
-    // Only "needs refinement" when there are candidates and at least one isn't grounded.
+    // Only "needs refinement" when there are initiatives and at least one isn't grounded.
     needs_refinement: items.length > 0 && grounded < items.length,
     items
   };
+  const wiCandidates = md ? parseRoadmapCandidates(md) : [];
+  const wcount = (pred) => wiCandidates.filter(pred).length;
+  const work_item_candidates = {
+    total: wiCandidates.length,
+    with_source_initiative: wcount((c) => Boolean(c.initiative?.id || c.initiative?.title)),
+    with_related_domain: wcount((c) => Boolean(c.domain)),
+    with_related_capability: wcount((c) => Boolean(c.relatedCapabilities?.length))
+  };
+  return { initiatives, work_item_candidates };
 }
 
 // src/core/project-explain.ts
@@ -8723,10 +8960,11 @@ function renderExplanationHuman(exp) {
   lines.push(`- Delivery: ${ls("Delivery")}`);
   lines.push(`- Agents: ${exp.knowledge.hasAgents ? "available" : "missing"}`);
   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}`);
+    lines.push(`- Roadmap initiatives: ${exp.roadmap.initiatives}`);
+    lines.push(`- Work Item candidates: ${exp.roadmap.work_item_candidates}`);
+    lines.push(`- Materialized Work Items: ${exp.roadmap.materialized_work_items}`);
+    if (exp.roadmap.remaining_work_item_candidates > 0)
+      lines.push(`- Remaining Work Item candidates: ${exp.roadmap.remaining_work_item_candidates}`);
   } else {
     lines.push(`- Work items: ${exp.workItems.total}`);
   }
@@ -8851,9 +9089,12 @@ function renderExplanationHuman(exp) {
   }
   lines.push(`- Next step: ${exp.readiness.recommended_next_step.label}`);
   lines.push("");
-  if (exp.suggestedNextSteps.length > 0) {
+  const rec = exp.nextStepRecommendation;
+  const secondary = rec.secondary ?? [];
+  const steps = secondary.length > 0 || /Delivery|Active|Maintenance/.test(rec.phase) ? [rec.label, ...secondary.map((s2) => s2.label)] : exp.suggestedNextSteps;
+  if (steps.length > 0) {
     lines.push("## Suggested Next Steps");
-    exp.suggestedNextSteps.forEach((s2, i) => lines.push(`${i + 1}. ${s2}`));
+    steps.forEach((s2, i) => lines.push(`${i + 1}. ${s2}`));
     lines.push("");
   }
   const r = exp.readiness;
@@ -8903,17 +9144,42 @@ function renderExplanationHuman(exp) {
     lines.push("Tech discovery files are in the legacy `knowledge/tech/` root. Suggested cleanup: run `kaddo tech organize`.");
     lines.push("");
   }
+  if (exp.roadmap.present) {
+    lines.push("## Roadmap Status");
+    lines.push(`- Initiatives: ${exp.roadmap.initiatives}`);
+    lines.push(`- Work Item candidates: ${exp.roadmap.work_item_candidates}`);
+    lines.push(`- Materialized Work Items: ${exp.roadmap.materialized_work_items}`);
+    lines.push(`- Remaining Work Item candidates: ${exp.roadmap.remaining_work_item_candidates}`);
+    lines.push("");
+  }
   const rq = exp.roadmapQuality;
-  if (rq.candidates > 0) {
+  const rqi = rq.initiatives;
+  const rqw = rq.work_item_candidates;
+  if (rqi.total > 0 || rqw.total > 0) {
     lines.push("## Roadmap Quality");
-    lines.push(`- Candidates: ${rq.candidates}`);
-    lines.push(`- Grounded: ${rq.grounded}/${rq.candidates}`);
-    lines.push(`- With related domain: ${rq.with_related_domain}/${rq.candidates}`);
-    lines.push(`- With related capability: ${rq.with_related_capability}/${rq.candidates}`);
-    lines.push(`- With source signals: ${rq.with_source_signals}/${rq.candidates}`);
-    if (rq.needs_refinement) {
+    if (rqi.total > 0) {
+      lines.push("Initiatives:");
+      lines.push(`- Candidates evaluated: ${rqi.total}`);
+      lines.push(`- Grounded: ${rqi.grounded}/${rqi.total}`);
+      lines.push(`- With related domain: ${rqi.with_related_domain}/${rqi.total}`);
+      lines.push(`- With related capability: ${rqi.with_related_capability}/${rqi.total}`);
+      lines.push(`- With source signals: ${rqi.with_source_signals}/${rqi.total}`);
+    }
+    if (rqw.total > 0) {
       lines.push("");
-      lines.push("Roadmap quality: needs refinement. Suggested: use roadmap-agent to add domain / capability / source signals.");
+      lines.push("Work Item Candidates:");
+      lines.push(`- Candidates: ${rqw.total}`);
+      lines.push(`- With source initiative: ${rqw.with_source_initiative}/${rqw.total}`);
+      lines.push(`- With related domain: ${rqw.with_related_domain}/${rqw.total}`);
+      lines.push(`- With related capability: ${rqw.with_related_capability}/${rqw.total}`);
+    }
+    if (rqi.needs_refinement) {
+      lines.push("");
+      lines.push("Roadmap quality: needs refinement.");
+      lines.push("Suggested: use roadmap-agent to add domain / capability / source signals.");
+    } else if (rqw.total > 0) {
+      lines.push("");
+      lines.push("Work Item candidate quality: good.");
     }
     lines.push("");
   }
@@ -9301,6 +9567,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     nextStep: nextStepRecommendation.label,
     recommendedAgents: nextStepRecommendation.agent ? [nextStepRecommendation.agent] : phase.recommendedAgents
   };
+  const deliveryState = { ...buildDeliveryState(dir), phase: nextStepRecommendation.phase };
   return {
     version: CONTEXT_PACK_VERSION,
     generatedAt: now.toISOString(),
@@ -9333,6 +9600,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase: unifiedPhase,
     nextStepRecommendation,
+    deliveryState,
     techDecisions,
     techKnowledge,
     roadmapQuality: buildRoadmapQuality(dir),
@@ -9397,6 +9665,31 @@ function renderContextPack(pack) {
     parts.push(`Next step: ${pack.phase.nextStep}
 `);
   }
+  const ds = pack.deliveryState;
+  const rec = pack.nextStepRecommendation;
+  if (ds.total_work_items > 0 || rec.phase !== "Setup") {
+    parts.push("## Delivery State\n");
+    parts.push(
+      [
+        `- Phase: ${ds.phase}`,
+        `- Draft Work Items: ${ds.draft_work_items}`,
+        `- Ready Work Items: ${ds.ready_work_items}`,
+        `- In-progress Work Items: ${ds.in_progress_work_items}`,
+        `- Ownership coverage: ${ds.ownership_coverage}`,
+        `- Remaining Work Item candidates: ${ds.remaining_work_item_candidates}`
+      ].join("\n") + "\n"
+    );
+    parts.push("## Next Step Recommendation\n");
+    const recLines = [`- ${rec.label}`, `  - id: ${rec.id}`, `  - reason: ${rec.reason}`];
+    if (rec.agent) recLines.push(`  - agent: ${rec.agent}`);
+    if (rec.skill) recLines.push(`  - skill: ${rec.skill}`);
+    if (rec.command) recLines.push(`  - command: \`${rec.command}\``);
+    parts.push(recLines.join("\n") + "\n");
+    if (rec.secondary && rec.secondary.length > 0) {
+      parts.push("Also (secondary):\n");
+      parts.push(rec.secondary.map((s) => `- ${s.label}`).join("\n") + "\n");
+    }
+  }
   parts.push("## Knowledge Layers\n");
   parts.push(
     "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
@@ -9434,35 +9727,52 @@ function renderContextPack(pack) {
   }
   parts.push("## Current Knowledge\n");
   parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
-  parts.push("## Roadmap\n");
+  parts.push("## Roadmap Status\n");
   if (pack.roadmap.present) {
     parts.push(
       [
-        `- Roadmap candidates: ${pack.roadmap.candidates}`,
-        `- Materialized work items: ${pack.roadmap.materialized}`,
-        `- Remaining candidates: ${pack.roadmap.remaining}`
+        `- Initiatives: ${pack.roadmap.initiatives}`,
+        `- Work Item candidates: ${pack.roadmap.work_item_candidates}`,
+        `- Materialized Work Items: ${pack.roadmap.materialized_work_items}`,
+        `- Remaining Work Item candidates: ${pack.roadmap.remaining_work_item_candidates}`
       ].join("\n") + "\n"
     );
-    if (pack.roadmap.remaining > 0) {
+    if (pack.roadmap.remaining_work_item_candidates > 0) {
       parts.push(
-        "Candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+        "Work Item candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
       );
     }
   }
   parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
   const rq = pack.roadmapQuality;
-  if (rq.candidates > 0) {
+  const rqi = rq.initiatives;
+  const rqw = rq.work_item_candidates;
+  if (rqi.total > 0 || rqw.total > 0) {
     parts.push("## Roadmap Quality\n");
-    parts.push(
-      [
-        `- Candidates: ${rq.candidates}`,
-        `- Grounded: ${rq.grounded}/${rq.candidates}`,
-        `- With related domain: ${rq.with_related_domain}/${rq.candidates}`,
-        `- With related capability: ${rq.with_related_capability}/${rq.candidates}`,
-        `- With source signals: ${rq.with_source_signals}/${rq.candidates}`
-      ].join("\n") + "\n"
-    );
-    if (rq.needs_refinement) {
+    if (rqi.total > 0) {
+      parts.push(
+        [
+          "Initiatives:",
+          `- Candidates evaluated: ${rqi.total}`,
+          `- Grounded: ${rqi.grounded}/${rqi.total}`,
+          `- With related domain: ${rqi.with_related_domain}/${rqi.total}`,
+          `- With related capability: ${rqi.with_related_capability}/${rqi.total}`,
+          `- With source signals: ${rqi.with_source_signals}/${rqi.total}`
+        ].join("\n") + "\n"
+      );
+    }
+    if (rqw.total > 0) {
+      parts.push(
+        [
+          "Work Item Candidates:",
+          `- Candidates: ${rqw.total}`,
+          `- With source initiative: ${rqw.with_source_initiative}/${rqw.total}`,
+          `- With related domain: ${rqw.with_related_domain}/${rqw.total}`,
+          `- With related capability: ${rqw.with_related_capability}/${rqw.total}`
+        ].join("\n") + "\n"
+      );
+    }
+    if (rqi.needs_refinement) {
       parts.push(
         "Roadmap quality: needs refinement. Use the roadmap-agent to add domain / capability / source signals.\n"
       );
@@ -9883,8 +10193,13 @@ function runUnderstand() {
     for (const r of assessment.reasons) console.log(`  - ${r}`);
   }
   if (rec.agent) console.log(`Recommended: ${rec.agent}`);
+  if (rec.skill) console.log(`Recommended skill: ${rec.skill}`);
   console.log(`Next step: ${rec.label}`);
   if (rec.reason) console.log(`Why: ${rec.reason}`);
+  if (rec.secondary && rec.secondary.length > 0) {
+    console.log("Also:");
+    for (const s of rec.secondary) console.log(`  - ${s.label}`);
+  }
   const installedSkills = discoverInstalledSkills(dir);
   if (installedSkills.length > 0 && assessment.recommendedAgents.length > 0) {
     const recSkills = skillsForAgents(installedSkills, assessment.recommendedAgents);
@@ -9900,15 +10215,15 @@ function runUnderstand() {
     console.log("  \u2192 Use the adr-writing skill to create ADR drafts from `knowledge/tech/decision-candidates.md`");
     console.log("    into `knowledge/tech/decisions/` before implementing affected technical Work Items (`kaddo adr`).");
   }
-  const rq = exp.roadmapQuality;
-  if (rq.needs_refinement) {
+  const rqi = exp.roadmapQuality.initiatives;
+  if (rqi.needs_refinement) {
     console.log("");
-    console.log(`Roadmap quality: ${rq.grounded}/${rq.candidates} candidates grounded.`);
-    console.log("  \u2192 Use roadmap-agent to ground roadmap candidates in capability domains, gaps and source signals");
+    console.log(`Roadmap quality: ${rqi.grounded}/${rqi.total} initiatives grounded.`);
+    console.log("  \u2192 Use roadmap-agent to ground roadmap initiatives in capability domains, gaps and source signals");
     console.log("    before `kaddo create --from roadmap`.");
-  } else if (rq.candidates > 0 && rq.grounded === rq.candidates) {
+  } else if (rqi.total > 0 && rqi.grounded === rqi.total && exp.roadmap.materialized_work_items === 0) {
     console.log("");
-    console.log("Roadmap candidates are grounded. \u2192 Run `kaddo create --from roadmap` to materialize the first Work Item.");
+    console.log("Roadmap initiatives are grounded. \u2192 Run `kaddo create --from roadmap` to materialize the first Work Item.");
   }
   const ia = exp.installedAssets;
   const outdatedRecommended = ia.agents.items.filter(

package/package.json

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