@kaddo/cli 3.42.0 → 3.43.0

package/README.md

@@ -541,6 +541,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.40.1 | ADR slug cleanup + MCP: suggested ADR filenames strip list/heading prefixes (no `ADR-001-1-…`) and normalize acronyms; new read-only MCP resource `kaddo://tech-decisions` sharing `buildTechDecisions` with `kaddo adr` |
 | 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` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -2645,6 +2645,24 @@ Adapt priorities to the project state from the context pack:
 - **legacy** \u2014 prioritize risk reduction, unknowns and safe modernization before feature
   delivery.
 
+## Grounding rules (VS-077)
+
+Every candidate initiative must be **grounded** in the knowledge base \u2014 never a loose idea. For each
+\`### RM-xxx\` you must provide:
+
+- **Related domain** \u2014 a domain from \`## Capability Domains\` in \`capabilities.md\` (or, if genuinely
+  new, prefix it \`[new candidate domain] <name>\` \u2014 do not invent domains silently).
+- **Related capabilities** \u2014 one or more existing/partial capabilities.
+- **Source signals** \u2014 at least one traceable reason: Capability Gap, Roadmap Candidate Signal, Risk,
+  Open Question, Assumption, Deferred Decision, Tech Decision Candidate, ADR, Business Goal,
+  Operational Need or Legacy Modernization Signal.
+- **Expected value**, **Risks**, **Dependencies**, and **Suggested Work Items** (candidates only).
+
+Do **not** emit a candidate with no source signal. Keep initiatives at initiative granularity (small
+tasks go under **Suggested Work Items**, not as their own RM). Every roadmap ends with a global
+**## Not Now** section. For pre-ai/legacy, prioritize stabilization, security, data, operations,
+architectural decisions and business-blocking gaps before expansive features.
+
 ## Constraints
 
 - Do not invent business priorities or business facts \u2014 mark them as assumptions when inferred.
@@ -2653,6 +2671,8 @@ Adapt priorities to the project state from the context pack:
   implementation-agent, and only after Work Items are materialized. Your handoff is
   \`kaddo create --from roadmap\` \u2192 work-item-agent.
 - Do not create the work items themselves; only propose candidates.
+- **Never create files under \`knowledge/delivery/work-items/\`** \u2014 materialization is
+  \`kaddo create --from roadmap\`, not the roadmap-agent.
 - Make clear that initiatives and work items are **candidates**, not final decisions.
 - Mark any uncertain information as an assumption or open question.
 - Keep sequencing justified by dependencies and risk.
@@ -2686,31 +2706,38 @@ human review \u2014 not final commitments.
 
 ### RM-001: <Initiative Name>
 
-**Goal:**
+**Status:** candidate <!-- candidate | selected | deferred | rejected -->
 
-**Related capabilities:**
+**Priority:** high / medium / low
+
+**Suggested Knowledge Level:** K1 / K2 / K3 / K4
 
-**Project area / domain:**
+**Related domain:** <one of the ## Capability Domains from capabilities.md>
 
-**Impact:** Low / Medium / High
+**Related capabilities:**
+- <existing or partial capability>
 
-**Risk:** Low / Medium / High
+**Source signals:** <!-- REQUIRED: why this candidate exists (at least one) -->
+- Capability Gap: <...>
+- Roadmap Candidate Signal: <...>
+- Risk / Open Question / Assumption / Deferred Decision / Tech Decision Candidate / ADR / Business Goal: <...>
 
-**Suggested Knowledge Level:** K1 / K2 / K3 / K4
+**Problem / opportunity:**
 
-**Dependencies:**
+**Expected value:**
 
-**Why this comes now:**
+**Risks:**
 
-**Candidate Work Items:**
+**Dependencies:**
 
+**Suggested Work Items:**
 - WI-CANDIDATE-001: <candidate work item>
   - type:
   - suggested knowledge level:
   - expected value:
   - notes:
 
-**Open questions:**
+**Not now:**
 
 ---
 
@@ -3005,6 +3032,14 @@ that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and
 without surfacing it. -->
 \`\`\`
 
+### Preserve roadmap metadata (VS-077)
+
+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.
+
 ## Where to Save the Result
 
 Save new output as a draft under \`knowledge/delivery/work-items/draft/\` unless a human
@@ -4979,6 +5014,16 @@ function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
     `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, "'")}"`,
     "---"
   ];
@@ -8325,6 +8370,79 @@ function installedAssetsSummary(dir) {
   return { version: KADDO_VERSION, agents: assetStatus(dir, "agent"), skills: assetStatus(dir, "skill") };
 }
 
+// src/core/roadmap-quality.ts
+var ROADMAP_PATH2 = "knowledge/delivery/roadmap.md";
+var INITIATIVE_RE2 = /^#{2,4}\s+(RM-[\w.-]+)\s*[:\-–]?\s*(.*)$/;
+function fieldPresent(lines, label) {
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(new RegExp(`^\\s*[-*]?\\s*(?:\\*\\*)?\\s*(${label.source})\\s*(?:\\*\\*)?\\s*:\\s*(.*)$`, "i"));
+    if (!m) continue;
+    const inline = m[2].trim();
+    if (inline) return true;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^\s{2,}[-*]\s+\S/.test(lines[j])) return true;
+      if (/^\S/.test(lines[j]) || /^#{2,4}\s/.test(lines[j])) break;
+      if (/^\s*[-*]\s+\S/.test(lines[j]) && !/^\s{2,}/.test(lines[j])) break;
+    }
+  }
+  return false;
+}
+function parseRoadmapCandidateQuality(md) {
+  const lines = md.split(/\r?\n/);
+  const items = [];
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    const hasRelatedDomain = fieldPresent(cur.lines, /related domain/);
+    const hasRelatedCapability = fieldPresent(cur.lines, /related capabilit(?:y|ies)/);
+    const hasSourceSignals = fieldPresent(cur.lines, /source signals?/);
+    items.push({
+      id: cur.id,
+      title: cur.title,
+      hasRelatedDomain,
+      hasRelatedCapability,
+      hasSourceSignals,
+      grounded: hasRelatedDomain && hasRelatedCapability && hasSourceSignals
+    });
+    cur = null;
+  };
+  for (const line of lines) {
+    const m = line.match(INITIATIVE_RE2);
+    if (m) {
+      flush();
+      cur = { id: m[1], title: m[2].trim(), lines: [] };
+      continue;
+    }
+    if (cur) cur.lines.push(line);
+  }
+  flush();
+  return items;
+}
+function buildRoadmapQuality(dir) {
+  let md = "";
+  const p2 = join(dir, ROADMAP_PATH2);
+  if (exists(p2)) {
+    try {
+      md = readFile(p2);
+    } catch {
+      md = "";
+    }
+  }
+  const items = parseRoadmapCandidateQuality(md);
+  const count = (pred) => items.filter(pred).length;
+  const grounded = count((i) => i.grounded);
+  return {
+    candidates: 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.
+    needs_refinement: items.length > 0 && grounded < items.length,
+    items
+  };
+}
+
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
 function normalizeTitle(t) {
@@ -8549,7 +8667,8 @@ function buildProjectExplanation(dir) {
         legacyLocation: exists(join(dir, "knowledge/tech/architecture-notes.md")) || exists(join(dir, "knowledge/tech/decision-candidates.md"))
       }
     },
-    installedAssets: installedAssetsSummary(dir)
+    installedAssets: installedAssetsSummary(dir),
+    roadmapQuality: buildRoadmapQuality(dir)
   };
 }
 function stateLabel(state) {
@@ -8784,6 +8903,20 @@ function renderExplanationHuman(exp) {
     lines.push("Tech discovery files are in the legacy `knowledge/tech/` root. Suggested cleanup: run `kaddo tech organize`.");
     lines.push("");
   }
+  const rq = exp.roadmapQuality;
+  if (rq.candidates > 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) {
+      lines.push("");
+      lines.push("Roadmap quality: needs refinement. Suggested: use roadmap-agent to add domain / capability / source signals.");
+    }
+    lines.push("");
+  }
   const ia = exp.installedAssets;
   const agentsInstalled = ia.agents.total - ia.agents.missing;
   const skillsInstalled = ia.skills.total - ia.skills.missing;
@@ -9202,6 +9335,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     nextStepRecommendation,
     techDecisions,
     techKnowledge,
+    roadmapQuality: buildRoadmapQuality(dir),
     installedAssets: (() => {
       const s = installedAssetsSummary(dir);
       const compact = (a) => ({ total: a.total, installed: a.total - a.missing, outdated: a.outdated, unknown_version: a.unknown_version, modified: a.modified });
@@ -9316,6 +9450,24 @@ function renderContextPack(pack) {
     }
   }
   parts.push((knowledge.roadmapSummary || "No roadmap baseline found.") + "\n");
+  const rq = pack.roadmapQuality;
+  if (rq.candidates > 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) {
+      parts.push(
+        "Roadmap quality: needs refinement. Use the roadmap-agent to add domain / capability / source signals.\n"
+      );
+    }
+  }
   parts.push("## Active Work Items\n");
   if (knowledge.workItems.length > 0) {
     const lines = knowledge.workItems.map((wi) => {
@@ -9748,6 +9900,16 @@ 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) {
+    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("    before `kaddo create --from roadmap`.");
+  } else if (rq.candidates > 0 && rq.grounded === rq.candidates) {
+    console.log("");
+    console.log("Roadmap candidates are grounded. \u2192 Run `kaddo create --from roadmap` to materialize the first Work Item.");
+  }
   const ia = exp.installedAssets;
   const outdatedRecommended = ia.agents.items.filter(
     (a) => (a.state === "outdated" || a.state === "unknown-version") && assessment.recommendedAgents.includes(a.name)

package/package.json

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