@kaddo/mcp 3.116.0 → 3.118.0

package/dist/index.js

@@ -393,13 +393,15 @@ import matter10 from "gray-matter";
 
 // ../cli/src/core/config.ts
 import { z } from "zod";
-import { parse as parseYaml2 } from "yaml";
+import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
 var PROJECT_STATES = ["new", "pre-ai", "legacy", "ai-assisted"];
+var PROJECT_MODES = ["standard", "poc"];
 var TEAM_SIZES = ["indie", "small", "medium", "enterprise"];
 var REPOSITORY_STRUCTURES = ["monorepo", "multirepo"];
 var PROJECT_LANGUAGES = ["en", "es"];
 var DEFAULTS = {
   state: "pre-ai",
+  mode: "standard",
   structure: "monorepo",
   teamSize: "indie",
   language: "en"
@@ -411,6 +413,9 @@ function projectLanguage(config) {
   const lang = config.project.language;
   return lang === "es" ? "es" : "en";
 }
+function projectMode(config) {
+  return config.project.mode === "poc" ? "poc" : "standard";
+}
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -422,6 +427,11 @@ var projectStateSchema = z.enum(["new", "pre-ai", "legacy", "ai-assisted"], {
     message: `project.state must be one of: ${PROJECT_STATES.join(", ")}`
   })
 });
+var projectModeSchema = z.enum(["standard", "poc"], {
+  errorMap: () => ({
+    message: `project.mode must be one of: ${PROJECT_MODES.join(", ")}`
+  })
+});
 var teamSizeSchema = z.enum(["indie", "small", "medium", "enterprise"], {
   errorMap: () => ({
     message: `team.size must be one of: ${TEAM_SIZES.join(", ")}`
@@ -443,6 +453,7 @@ var configSchema = z.object({
   project: z.object({
     name: z.string().default("project"),
     state: projectStateSchema.default(DEFAULTS.state),
+    mode: projectModeSchema.default(DEFAULTS.mode),
     structure: structureSchema.default(DEFAULTS.structure),
     language: languageSchema.default(DEFAULTS.language),
     role: multirepoRoleSchema,
@@ -891,7 +902,7 @@ function assessPhase(input) {
 
 // ../cli/src/core/capsule.ts
 import matter4 from "gray-matter";
-import { parse as parseYaml7, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml7, stringify as stringifyYaml4 } from "yaml";
 
 // ../cli/src/services/owners.ts
 import { parse as parseYaml3 } from "yaml";
@@ -1145,7 +1156,7 @@ var Q2 = o("\u25B2", "!");
 var ee = o("\u25A0", "x");
 
 // ../cli/src/commands/modules-map.ts
-import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
+import { parse as parseYaml6, stringify as stringifyYaml3 } from "yaml";
 
 // ../cli/src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -2309,7 +2320,7 @@ ${QUALITY}
 `;
 
 // ../cli/src/commands/modules-discover.ts
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml5, stringify as stringifyYaml2 } from "yaml";
 
 // ../cli/src/core/capsule.ts
 var KNOWLEDGE2 = "knowledge";
@@ -4312,6 +4323,43 @@ function buildTechDecisions(dir) {
   };
 }
 
+// ../cli/src/core/poc.ts
+var POC_ARTIFACT_PATH = "knowledge/delivery/poc.md";
+var PLACEHOLDER = /^[_<].*[_>]$|^(describe|list|document|what|how)\b/i;
+function section2(markdown, heading) {
+  const match = markdown.match(new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im"));
+  return match?.[1] ?? "";
+}
+function meaningful(text3) {
+  return text3.split(/\r?\n/).some((line) => {
+    const value = line.trim().replace(/^[-*]\s+(?:\[[^\]]+\]\s*)?/, "");
+    return Boolean(value) && !PLACEHOLDER.test(value) && !/^status:\s*(pending|tbd)$/i.test(value);
+  });
+}
+function readPocSummary(dir) {
+  const path9 = join(dir, POC_ARTIFACT_PATH);
+  if (!exists(path9)) {
+    return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
+  }
+  let markdown = "";
+  try {
+    markdown = readFile(path9);
+  } catch {
+    return { exists: false, hypothesisDefined: false, successCriteriaCount: 0, constraintsDefined: false, nonGoalsDefined: false, conclusion: "pending" };
+  }
+  const criteria = section2(markdown, "Success Criteria").split(/\r?\n/).filter((line) => /^\s*[-*]\s+(?:\[[ xX]\]\s+)?/.test(line)).filter((line) => meaningful(line)).length;
+  const conclusionBody = section2(markdown, "Conclusion");
+  const conclusionMatch = conclusionBody.match(/\b(?:status|outcome)\s*:\s*(validated|rejected|inconclusive)\b/i);
+  return {
+    exists: true,
+    hypothesisDefined: meaningful(section2(markdown, "Hypothesis")),
+    successCriteriaCount: criteria,
+    constraintsDefined: meaningful(section2(markdown, "Constraints")),
+    nonGoalsDefined: meaningful(section2(markdown, "Non-goals")),
+    conclusion: conclusionMatch ? conclusionMatch[1].toLowerCase() : "pending"
+  };
+}
+
 // ../cli/src/core/next-step.ts
 function buildDeliveryState(dir) {
   const wis = discoverWorkItems(dir);
@@ -4399,6 +4447,37 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     return { id: "init", phase: "Setup", label: "Run `kaddo init` to initialize Kaddo.", command: "kaddo init", reason: "Kaddo is not initialized in this project." };
   }
   const state = config.project.state;
+  if (projectMode(config) === "poc") {
+    const poc = readPocSummary(dir);
+    if (!poc.exists) {
+      return { id: "poc-artifact", phase: "POC Definition", label: "Create or restore the POC artifact.", command: "kaddo project mode poc", target: POC_ARTIFACT_PATH, reason: `Missing ${POC_ARTIFACT_PATH}.` };
+    }
+    if (!poc.hypothesisDefined) {
+      return { id: "poc-hypothesis", phase: "POC Definition", label: "Define the POC hypothesis.", target: POC_ARTIFACT_PATH, reason: "The POC needs a testable hypothesis before work begins." };
+    }
+    if (poc.successCriteriaCount === 0) {
+      return { id: "poc-success-criteria", phase: "POC Definition", label: "Define observable POC success criteria.", target: POC_ARTIFACT_PATH, reason: "No success criteria are defined for the hypothesis." };
+    }
+    const qCurrentState2 = analyzeKnowledgeArtifact(dir, CS);
+    const qCodebase2 = analyzeKnowledgeArtifact(dir, CB);
+    if (exists(join(dir, ".kaddo", "scan.json")) && (qCurrentState2 !== "useful" || qCodebase2 !== "useful")) {
+      return { id: "poc-technical-context", phase: "POC Discovery", label: "Document the minimal technical context for the experiment.", target: qCurrentState2 !== "useful" ? CS : CB, agent: "architecture-agent", reason: "The experiment surface and constraints are not yet sufficiently documented." };
+    }
+    const delivery = buildDeliveryState(dir);
+    if (delivery.total_work_items === 0) {
+      return { id: "poc-create-experiment", phase: "Experiment", label: "Create the first experiment Work Item (prefer `spike`).", command: "kaddo create spike", reason: "The POC has no Work Item to produce evidence." };
+    }
+    if (delivery.in_progress_work_items > 0) {
+      return { id: "guard", phase: "Experiment", label: "Run `kaddo guard` and capture evidence from the experiment.", command: "kaddo guard", reason: `${delivery.in_progress_work_items} experiment Work Item(s) are in progress.` };
+    }
+    if (delivery.ready_work_items > 0 || delivery.draft_work_items > 0 || delivery.blocked_work_items > 0) {
+      return { id: delivery.ready_work_items > 0 ? "implement-work-item" : "refine-work-item", phase: "Experiment", label: delivery.ready_work_items > 0 ? "Implement the ready experiment Work Item and collect evidence." : "Refine the experiment Work Item before running it.", agent: "work-item-agent", reason: "The POC evidence Work Item is not complete yet." };
+    }
+    if (poc.conclusion === "pending") {
+      return { id: "poc-evaluate", phase: "Evaluation", label: "Evaluate the experiment evidence and record the POC conclusion.", target: POC_ARTIFACT_PATH, reason: "Experiment Work Items are complete but the POC conclusion is pending." };
+    }
+    return { id: "poc-complete", phase: "Conclusion", label: `POC concluded: ${poc.conclusion}. Decide whether to graduate it to standard delivery.`, target: POC_ARTIFACT_PATH, reason: "The POC conclusion is recorded from experiment evidence." };
+  }
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const resolveAgent = (agent) => {
     const file = agent.endsWith(".md") ? agent : `${agent}.md`;
@@ -8650,6 +8729,56 @@ var LEGACY_STEPS = [
   runGuard,
   captureLearning
 ];
+var definePocHypothesis = {
+  id: "poc-hypothesis",
+  label: "Define hypothesis",
+  evaluate: (ctx) => {
+    const poc = readPocSummary(ctx.dir);
+    return { status: poc.hypothesisDefined ? "done" : "current", evidence: poc.hypothesisDefined ? [POC_ARTIFACT_PATH] : void 0, reason: poc.hypothesisDefined ? void 0 : "A POC starts with one testable hypothesis." };
+  }
+};
+var ensurePocArtifact = {
+  id: "poc-artifact",
+  label: "Create POC artifact",
+  evaluate: (ctx) => exists(join(ctx.dir, POC_ARTIFACT_PATH)) ? { status: "done", evidence: [POC_ARTIFACT_PATH] } : { status: "current", command: "kaddo project mode poc", reason: "Create the canonical POC artifact before defining the experiment." }
+};
+var definePocCriteria = {
+  id: "poc-success-criteria",
+  label: "Define success criteria",
+  evaluate: (ctx) => {
+    const poc = readPocSummary(ctx.dir);
+    return { status: poc.successCriteriaCount > 0 ? "done" : "pending", evidence: poc.successCriteriaCount > 0 ? [POC_ARTIFACT_PATH] : void 0, reason: poc.successCriteriaCount > 0 ? void 0 : "Define observable evidence for the hypothesis." };
+  }
+};
+var describePocTech = {
+  id: "poc-technical-context",
+  label: "Document minimal technical context",
+  evaluate: (ctx) => ctx.hasScan ? describeArchitecture.evaluate(ctx) : { status: "optional", command: "kaddo scan", reason: "Add technical context only when the experiment needs to inspect existing code." }
+};
+var identifyPocResources = {
+  id: "poc-resources",
+  label: "Identify relevant resources",
+  evaluate: (ctx) => exists(join(ctx.dir, "knowledge/resources")) ? { status: "done", evidence: ["knowledge/resources/"] } : { status: "optional", command: "kaddo resources list", reason: "Add Project Resources only when the experiment depends on external systems." }
+};
+var createPocExperiment = {
+  id: "poc-create-experiment",
+  label: "Create experiment Work Item",
+  evaluate: (ctx) => ctx.totalWorkItems > 0 ? { status: "done", evidence: ["knowledge/delivery/work-items/"] } : { status: "pending", command: "kaddo create spike", reason: "Prefer a spike for a focused experiment." }
+};
+var capturePocEvidence = {
+  id: "poc-evidence",
+  label: "Capture experiment evidence",
+  evaluate: (ctx) => ctx.completedWorkItems > 0 ? { status: "done", evidence: ["knowledge/delivery/work-items/"] } : { status: "pending", reason: "Complete an experiment Work Item and link its evidence in the POC artifact." }
+};
+var concludePoc = {
+  id: "poc-evaluate",
+  label: "Evaluate and conclude",
+  evaluate: (ctx) => {
+    const conclusion = readPocSummary(ctx.dir).conclusion;
+    return conclusion === "pending" ? { status: "pending", reason: "Record validated, rejected, or inconclusive from the evidence." } : { status: "done", evidence: [POC_ARTIFACT_PATH], reason: `Conclusion: ${conclusion}.` };
+  }
+};
+var POC_STEPS = [enableKaddo, ensurePocArtifact, definePocHypothesis, definePocCriteria, describePocTech, identifyPocResources, createPocExperiment, capturePocEvidence, concludePoc];
 function stepsForState(state) {
   switch (state) {
     case "new":
@@ -8746,14 +8875,21 @@ function mapNextStepId(id) {
     "init-module-context": "enable-kaddo",
     "module-ready": "ready-for-core-orchestration",
     "validate-work-item-modules": "validate-module-knowledge",
-    "modules-discover": "enable-kaddo"
+    "modules-discover": "enable-kaddo",
+    "poc-hypothesis": "poc-hypothesis",
+    "poc-success-criteria": "poc-success-criteria",
+    "poc-technical-context": "poc-technical-context",
+    "poc-resources": "poc-resources",
+    "poc-create-experiment": "poc-create-experiment",
+    "poc-evaluate": "poc-evaluate",
+    "poc-complete": "poc-evaluate"
   };
   return MAP[id] ?? id;
 }
 function buildProjectRoute(dir) {
   const config = loadConfig(dir);
   const state = config?.project.state ?? "pre-ai";
-  const defs = config && isModule(config) ? MODULE_STEPS : stepsForState(state);
+  const defs = config && projectMode(config) === "poc" ? POC_STEPS : config && isModule(config) ? MODULE_STEPS : stepsForState(state);
   const ctx = buildRouteContext(dir);
   const steps = defs.map((d3) => {
     const result = d3.evaluate(ctx);
@@ -10826,6 +10962,18 @@ var RESOURCES = [
       "Roadmap not found. Create knowledge/delivery/roadmap.md (e.g. via the roadmap-agent) first."
     )
   },
+  {
+    uri: "kaddo://poc",
+    name: "Kaddo proof of concept",
+    description: "Canonical POC hypothesis, success criteria, evidence, and conclusion.",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://poc",
+      "knowledge/delivery/poc.md",
+      "POC artifact not found. Initialize in POC mode or switch with `kaddo project mode poc`."
+    )
+  },
   {
     uri: "kaddo://capsules",
     name: "Kaddo knowledge capsules",
@@ -11115,14 +11263,14 @@ import matter15 from "gray-matter";
 import fs3 from "fs";
 import path3 from "path";
 import { z as z3 } from "zod";
-import { parse as parseYaml10 } from "yaml";
+import { parse as parseYaml10, stringify as stringifyYaml5 } from "yaml";
 import matter12 from "gray-matter";
 import matter22 from "gray-matter";
-import { parse as parseYaml62, stringify as stringifyYaml32 } from "yaml";
+import { parse as parseYaml62, stringify as stringifyYaml42 } from "yaml";
 import { parse as parseYaml22 } from "yaml";
 import { parse as parseYaml32 } from "yaml";
-import { parse as parseYaml52, stringify as stringifyYaml22 } from "yaml";
-import { parse as parseYaml42, stringify as stringifyYaml4 } from "yaml";
+import { parse as parseYaml52, stringify as stringifyYaml32 } from "yaml";
+import { parse as parseYaml42, stringify as stringifyYaml22 } from "yaml";
 import matter32 from "gray-matter";
 import matter42 from "gray-matter";
 import matter52 from "gray-matter";
@@ -11134,7 +11282,7 @@ import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import matter72 from "gray-matter";
 import matter82 from "gray-matter";
 import matter92 from "gray-matter";
-import { parse as parseYaml82, stringify as stringifyYaml42 } from "yaml";
+import { parse as parseYaml82, stringify as stringifyYaml52 } from "yaml";
 import fs4 from "fs";
 import path4 from "path";
 import crypto2 from "crypto";
@@ -11143,8 +11291,8 @@ import crypto3 from "crypto";
 import fs5 from "fs";
 import matter112 from "gray-matter";
 import matter122 from "gray-matter";
-import { parse as parseYaml92, stringify as stringifyYaml5 } from "yaml";
-import { parse as parseYaml102, stringify as stringifyYaml6 } from "yaml";
+import { parse as parseYaml92, stringify as stringifyYaml6 } from "yaml";
+import { parse as parseYaml102, stringify as stringifyYaml7 } from "yaml";
 import matter13 from "gray-matter";
 function exists2(p) {
   return fs3.existsSync(p);
@@ -11170,11 +11318,13 @@ function join3(...parts) {
   return path3.join(...parts);
 }
 var PROJECT_STATES2 = ["new", "pre-ai", "legacy", "ai-assisted"];
+var PROJECT_MODES2 = ["standard", "poc"];
 var TEAM_SIZES2 = ["indie", "small", "medium", "enterprise"];
 var REPOSITORY_STRUCTURES2 = ["monorepo", "multirepo"];
 var PROJECT_LANGUAGES2 = ["en", "es"];
 var DEFAULTS2 = {
   state: "pre-ai",
+  mode: "standard",
   structure: "monorepo",
   teamSize: "indie",
   language: "en"
@@ -11190,6 +11340,11 @@ var projectStateSchema2 = z3.enum(["new", "pre-ai", "legacy", "ai-assisted"], {
     message: `project.state must be one of: ${PROJECT_STATES2.join(", ")}`
   })
 });
+var projectModeSchema2 = z3.enum(["standard", "poc"], {
+  errorMap: () => ({
+    message: `project.mode must be one of: ${PROJECT_MODES2.join(", ")}`
+  })
+});
 var teamSizeSchema2 = z3.enum(["indie", "small", "medium", "enterprise"], {
   errorMap: () => ({
     message: `team.size must be one of: ${TEAM_SIZES2.join(", ")}`
@@ -11211,6 +11366,7 @@ var configSchema2 = z3.object({
   project: z3.object({
     name: z3.string().default("project"),
     state: projectStateSchema2.default(DEFAULTS2.state),
+    mode: projectModeSchema2.default(DEFAULTS2.mode),
     structure: structureSchema2.default(DEFAULTS2.structure),
     language: languageSchema2.default(DEFAULTS2.language),
     role: multirepoRoleSchema2,
@@ -19306,7 +19462,7 @@ function persistConsent(dir, consent) {
   const prev = doc.telemetry ?? {};
   delete prev.enabled;
   doc.telemetry = { ...prev, consent, consentVersion: CURRENT_CONSENT_VERSION };
-  writeFile2(configPath, stringifyYaml6(doc));
+  writeFile2(configPath, stringifyYaml7(doc));
 }
 function isDeferralActive(dir) {
   const p = join3(dir, ".kaddo", "telemetry-deferred.json");
@@ -20257,7 +20413,7 @@ function deleteResourceTool(root, id, confirm2) {
 import fs7 from "fs";
 import path6 from "path";
 import matter16 from "gray-matter";
-import { parse as parseYaml11, stringify as stringifyYaml7 } from "yaml";
+import { parse as parseYaml11, stringify as stringifyYaml8 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
 function moduleRepoPath(m2) {
@@ -20747,7 +20903,7 @@ function modulesDiscoverTool(root, args) {
         descriptor.modules.push({ id: d3.id, name: d3.id, path: d3.path, parent_system: sysName, status: "configured" });
       }
     }
-    const ymlContent = stringifyYaml7({ version: descriptor.version ?? 1, system: sysName, workspace_roots: workspaceRoots2, modules: descriptor.modules ?? [] });
+    const ymlContent = stringifyYaml8({ version: descriptor.version ?? 1, system: sysName, workspace_roots: workspaceRoots2, modules: descriptor.modules ?? [] });
     writeDerived(root, ".kaddo/modules.yml", ymlContent);
     return ok2({ discovered, applied: true });
   }
@@ -20793,7 +20949,7 @@ ${list3(data.owners)}
 }
 
 // ../cli/src/core/system-topology.ts
-import { parse as parseYaml12, stringify as stringifyYaml8 } from "yaml";
+import { parse as parseYaml12, stringify as stringifyYaml9 } from "yaml";
 import fs8 from "fs";
 import path7 from "path";
 import crypto from "crypto";
@@ -21308,7 +21464,7 @@ function systemImpactCandidatesTool(root, args) {
 
 // ../cli/src/services/integrations.ts
 import matter18 from "gray-matter";
-import { parse as parseYaml13, stringify as stringifyYaml9 } from "yaml";
+import { parse as parseYaml13, stringify as stringifyYaml10 } from "yaml";
 
 // ../cli/src/core/work-item-write.ts
 import fs9 from "fs";
@@ -22481,6 +22637,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
+  const mode = projectMode(config);
   const roadmapPath = join(dir, ARCH_DIR4, "delivery", "roadmap.md");
   const materialized = allArtifacts.filter(
     (a2) => a2.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a2.type)
@@ -22573,6 +22730,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     project: {
       name: config.project.name,
       state,
+      mode,
       teamSize: config.team.size,
       structure: config.project.structure,
       language: languageLabel(projectLanguage(config))
@@ -22598,6 +22756,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       allWorkItems: allWorkItemArtifacts.map(toContextWorkItem),
       artifacts: allArtifacts.filter((a2) => a2.codeGlobs.length > 0).map(toContextArtifact)
     },
+    ...mode === "poc" ? { poc: readPocSummary(dir) } : {},
     layers,
     knowledgeQuality,
     roadmap,
@@ -22701,11 +22860,23 @@ function renderContextPack(pack) {
     [
       `- Name: ${project.name}`,
       `- State: ${project.state}`,
+      `- Mode: ${project.mode}`,
       `- Team size: ${project.teamSize}`,
       `- Structure: ${project.structure}`,
       `- Language: ${project.language}`
     ].join("\n") + "\n"
   );
+  if (pack.poc) {
+    parts.push("## Proof of Concept\n");
+    parts.push([
+      `- Hypothesis: ${pack.poc.hypothesisDefined ? "defined" : "missing"}`,
+      `- Success criteria: ${pack.poc.successCriteriaCount}`,
+      `- Constraints: ${pack.poc.constraintsDefined ? "defined" : "missing"}`,
+      `- Non-goals: ${pack.poc.nonGoalsDefined ? "defined" : "missing"}`,
+      `- Conclusion: ${pack.poc.conclusion}`,
+      "- Canonical artifact: `knowledge/delivery/poc.md`"
+    ].join("\n") + "\n");
+  }
   parts.push("## Current Phase\n");
   parts.push(`Phase: ${pack.phase.phase}
 `);
@@ -22789,27 +22960,29 @@ function renderContextPack(pack) {
   }
   parts.push("## Current Knowledge\n");
   parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
-  parts.push("## Roadmap Status\n");
-  if (pack.roadmap.present) {
-    parts.push(
-      [
-        `- 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_work_item_candidates > 0) {
+  if (project.mode !== "poc") {
+    parts.push("## Roadmap Status\n");
+    if (pack.roadmap.present) {
       parts.push(
-        "Work Item candidates are not yet Work Items. Materialize them with `kaddo create --from roadmap`.\n"
+        [
+          `- 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_work_item_candidates > 0) {
+        parts.push(
+          "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");
   }
-  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) {
+  if (project.mode !== "poc" && (rqi.total > 0 || rqw.total > 0)) {
     parts.push("## Roadmap Quality\n");
     if (rqi.total > 0) {
       parts.push(
@@ -23024,7 +23197,13 @@ function renderContextPack(pack) {
 function agentIsInstalled(dir, fileName) {
   return exists(join(dir, agentInstallPath(fileName))) || exists(join(dir, "knowledge", "agents", fileName));
 }
-function flowForState(state) {
+function flowForState(state, mode) {
+  if (mode === "poc") {
+    return [
+      { agent: "architecture-agent.md", output: "knowledge/tech/current-state.md" },
+      { agent: "work-item-agent.md", output: "knowledge/delivery/poc.md" }
+    ];
+  }
   switch (state) {
     case "new":
       return [
@@ -23049,9 +23228,10 @@ function flowForState(state) {
 }
 function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
+  const mode = projectMode(config);
   if (isModule(config)) {
     return {
-      project: { name: config.project.name, state, teamSize: config.team.size, structure: config.project.structure, language: "English" },
+      project: { name: config.project.name, state, mode, teamSize: config.team.size, structure: config.project.structure, language: "English" },
       steps: [],
       missingAgents: [],
       agentsInstalled: true,
@@ -23059,7 +23239,7 @@ function buildUnderstandPlan(dir, config) {
       contextPackPath: ".kaddo/context-pack.md"
     };
   }
-  const flow = flowForState(state).filter((s) => !exists(join(dir, s.output)));
+  const flow = flowForState(state, mode).filter((s) => !exists(join(dir, s.output)));
   const steps = flow.map((s) => {
     const installed = agentIsInstalled(dir, s.agent);
     return { agent: s.agent, output: s.output, installed };
@@ -23070,6 +23250,7 @@ function buildUnderstandPlan(dir, config) {
     project: {
       name: config.project.name,
       state,
+      mode,
       teamSize: config.team.size,
       structure: config.project.structure,
       language: "English"

package/package.json

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