@kaddo/mcp 3.42.0 → 3.44.0

package/dist/index.js

@@ -1629,7 +1629,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;
@@ -1679,7 +1684,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";
@@ -1690,6 +1695,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;
     }
@@ -1707,6 +1715,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,
@@ -1715,9 +1724,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*(.*)$/;
@@ -1799,10 +1822,36 @@ 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
+  };
 }
 
 // ../cli/src/core/open-questions.ts
@@ -3628,6 +3677,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.
@@ -3636,6 +3703,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.
@@ -3669,31 +3738,38 @@ human review \u2014 not final commitments.
 
 ### RM-001: <Initiative Name>
 
-**Goal:**
+**Status:** candidate <!-- candidate | selected | deferred | rejected -->
 
-**Related capabilities:**
+**Priority:** high / medium / low
 
-**Project area / domain:**
+**Suggested Knowledge Level:** K1 / K2 / K3 / K4
 
-**Impact:** Low / Medium / High
+**Related domain:** <one of the ## Capability Domains from capabilities.md>
 
-**Risk:** Low / Medium / High
+**Related capabilities:**
+- <existing or partial capability>
 
-**Suggested Knowledge Level:** K1 / K2 / K3 / K4
+**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: <...>
 
-**Dependencies:**
+**Problem / opportunity:**
 
-**Why this comes now:**
+**Expected value:**
 
-**Candidate Work Items:**
+**Risks:**
 
+**Dependencies:**
+
+**Suggested Work Items:**
 - WI-CANDIDATE-001: <candidate work item>
   - type:
   - suggested knowledge level:
   - expected value:
   - notes:
 
-**Open questions:**
+**Not now:**
 
 ---
 
@@ -3988,6 +4064,23 @@ that it should be materialized first (\`kaddo adr\` + the adr-writing skill) and
 without surfacing it. -->
 \`\`\`
 
+### Preserve roadmap metadata (VS-077 / VS-078)
+
+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
 
 Save new output as a draft under \`knowledge/delivery/work-items/draft/\` unless a human
@@ -5208,6 +5301,88 @@ function installedAssetsSummary(dir) {
   return { version: KADDO_VERSION, agents: assetStatus(dir, "agent"), skills: assetStatus(dir, "skill") };
 }
 
+// ../cli/src/core/roadmap-quality.ts
+var ROADMAP_PATH = "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 p = join(dir, ROADMAP_PATH);
+  if (exists(p)) {
+    try {
+      md = readFile(p);
+    } catch {
+      md = "";
+    }
+  }
+  const items = parseRoadmapCandidateQuality(md);
+  const count = (pred) => items.filter(pred).length;
+  const grounded = count((i) => i.grounded);
+  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 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 };
+}
+
 // ../cli/src/core/project-explain.ts
 var ARCH_DIR2 = "knowledge";
 function normalizeTitle(t) {
@@ -5432,7 +5607,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) {
@@ -5487,10 +5663,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}`);
   }
@@ -5667,6 +5844,45 @@ 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;
+  const rqi = rq.initiatives;
+  const rqw = rq.work_item_candidates;
+  if (rqi.total > 0 || rqw.total > 0) {
+    lines.push("## Roadmap Quality");
+    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("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("");
+  }
   const ia = exp.installedAssets;
   const agentsInstalled = ia.agents.total - ia.agents.missing;
   const skillsInstalled = ia.skills.total - ia.skills.missing;
@@ -6892,6 +7108,32 @@ var RESOURCES = [
       }
       return [{ uri: "kaddo://installed-assets", text: JSON.stringify(installedAssetsSummary(root), null, 2), mimeType: "application/json" }];
     }
+  },
+  {
+    uri: "kaddo://roadmap-quality",
+    name: "Kaddo roadmap quality",
+    description: "How well roadmap initiatives and Work Item candidates are grounded in capability domains, related capabilities and source signals (VS-077 / VS-077.1). Two levels: initiatives + work_item_candidates. Read-only.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://roadmap-quality", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [{ uri: "kaddo://roadmap-quality", text: JSON.stringify(buildRoadmapQuality(root), null, 2), mimeType: "application/json" }];
+    }
+  },
+  {
+    uri: "kaddo://work-item-candidates",
+    name: "Kaddo work item candidates",
+    description: "Materializable Work Item candidates (WI-CANDIDATE-xxx) parsed from the roadmap, with their source initiative and inherited metadata (VS-078). Read-only.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://work-item-candidates", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      const md = readText(root, "knowledge/delivery/roadmap.md");
+      const candidates = md ? parseRoadmapCandidates(md) : [];
+      return [{ uri: "kaddo://work-item-candidates", text: JSON.stringify({ candidates }, null, 2), mimeType: "application/json" }];
+    }
   }
 ];
 
@@ -7220,6 +7462,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 });
@@ -7318,22 +7561,57 @@ 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;
+  const rqi = rq.initiatives;
+  const rqw = rq.work_item_candidates;
+  if (rqi.total > 0 || rqw.total > 0) {
+    parts.push("## Roadmap Quality\n");
+    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"
+      );
+    }
+  }
   parts.push("## Active Work Items\n");
   if (knowledge.workItems.length > 0) {
     const lines = knowledge.workItems.map((wi) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.42.0",
+  "version": "3.44.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {