@kaddo/mcp 3.46.0 → 3.48.0

package/dist/index.js

@@ -5516,6 +5516,453 @@ function buildRoadmapQuality(dir) {
   return { initiatives, work_item_candidates };
 }
 
+// ../cli/src/core/scan-signals.ts
+function signalCount(signals) {
+  return Object.values(signals).reduce((sum, arr) => sum + arr.length, 0);
+}
+function hasWarnings(signals) {
+  return signals.tests.some((s) => s.label.includes("No test directory"));
+}
+function renderSignalsCompact(signals) {
+  const lines = [];
+  const CATEGORIES = [
+    ["auth", "Auth"],
+    ["payments", "Payments"],
+    ["webhooks", "Webhooks"],
+    ["storage", "Storage"],
+    ["background_jobs", "Background jobs"],
+    ["email", "Email"],
+    ["database", "Database"],
+    ["migrations", "Migrations"],
+    ["api_routes", "API routes"],
+    ["tests", "Tests"],
+    ["security", "Security"],
+    ["infrastructure", "Infrastructure"],
+    ["external_integrations", "External integrations"],
+    ["environment", "Environment"]
+  ];
+  for (const [key, label] of CATEGORIES) {
+    const arr = signals[key];
+    if (arr.length === 0) continue;
+    if (arr.length === 1) {
+      lines.push(`- ${label}: ${arr[0].label}`);
+    } else {
+      lines.push(`- ${label}: ${arr.length}`);
+    }
+  }
+  return lines.length > 0 ? lines.join("\n") + "\n" : "No signals detected.\n";
+}
+
+// ../cli/src/core/project-route.ts
+function isUseful(q) {
+  return q === "useful";
+}
+var enableKaddo = {
+  id: "enable-kaddo",
+  label: "Enable Kaddo",
+  evaluate: (ctx) => ({
+    status: ctx.hasConfig ? "done" : "current",
+    evidence: ctx.hasConfig ? [".kaddo/config.yml"] : void 0,
+    command: ctx.hasConfig ? void 0 : "kaddo init"
+  })
+};
+var scanRepository = {
+  id: "scan-repository",
+  label: "Scan repository",
+  evaluate: (ctx) => {
+    if (!ctx.hasScan) return { status: "pending", command: "kaddo scan" };
+    if (ctx.hasScanWarnings) return { status: "warning", evidence: [".kaddo/scan.json"], reason: "Scan has warnings (e.g. no test directory detected).", command: "kaddo scan" };
+    return { status: "done", evidence: [".kaddo/scan.json"] };
+  }
+};
+var defineBusiness = {
+  id: "define-business",
+  label: "Define business context",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qBusiness) ? "done" : ctx.qBusiness === "missing" ? "pending" : "warning",
+    evidence: isUseful(ctx.qBusiness) ? ["knowledge/business/business.md"] : void 0,
+    reason: ctx.qBusiness === "placeholder" ? "Business context is still a bootstrap placeholder." : void 0,
+    agent: isUseful(ctx.qBusiness) ? void 0 : "business-agent"
+  })
+};
+var defineProduct = {
+  id: "define-product",
+  label: "Define product context",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qProduct) ? "done" : ctx.qProduct === "missing" ? "pending" : "warning",
+    evidence: isUseful(ctx.qProduct) ? ["knowledge/product/product.md"] : void 0,
+    agent: isUseful(ctx.qProduct) ? void 0 : "capability-agent"
+  })
+};
+var discoverCapabilities = {
+  id: "discover-capabilities",
+  label: "Discover capabilities",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qCapabilities) ? "done" : ctx.qCapabilities === "missing" ? "pending" : "warning",
+    evidence: isUseful(ctx.qCapabilities) ? ["knowledge/product/capabilities.md"] : void 0,
+    agent: isUseful(ctx.qCapabilities) ? void 0 : "capability-agent"
+  })
+};
+var describeArchitecture = {
+  id: "describe-architecture",
+  label: "Describe current architecture",
+  evaluate: (ctx) => {
+    const done = isUseful(ctx.qCurrentState) && isUseful(ctx.qCodebase);
+    const evidence = [];
+    if (isUseful(ctx.qCurrentState)) evidence.push("knowledge/tech/current-state.md");
+    if (isUseful(ctx.qCodebase)) evidence.push("knowledge/tech/codebase.md");
+    return {
+      status: done ? "done" : "pending",
+      evidence: evidence.length > 0 ? evidence : void 0,
+      agent: done ? void 0 : "architecture-agent"
+    };
+  }
+};
+var captureTechDecisions = {
+  id: "capture-technical-decisions",
+  label: "Capture technical decisions",
+  evaluate: (ctx) => {
+    if (ctx.decisionCandidates === 0 && ctx.totalAdrs === 0) {
+      return { status: "optional", reason: "No decision candidates found." };
+    }
+    if (ctx.totalAdrs > 0) {
+      return { status: "done", evidence: ["knowledge/tech/decisions/"], reason: `${ctx.totalAdrs} ADR(s) exist.` };
+    }
+    return {
+      status: "warning",
+      reason: `${ctx.decisionCandidates} decision candidate(s) exist but no ADRs have been materialized.`,
+      command: "kaddo adr",
+      skill: "adr-writing"
+    };
+  }
+};
+var createWorkSource = {
+  id: "create-work-source",
+  label: "Create or connect work source",
+  evaluate: (ctx) => ({
+    status: ctx.hasRoadmap || ctx.totalWorkItems > 0 ? "done" : "pending",
+    evidence: ctx.hasRoadmap ? ["knowledge/delivery/roadmap.md"] : void 0,
+    command: ctx.hasRoadmap ? void 0 : "kaddo roadmap",
+    agent: ctx.hasRoadmap ? void 0 : "roadmap-agent"
+  })
+};
+var materializeWorkItem = {
+  id: "materialize-work-item",
+  label: "Materialize first Work Item",
+  evaluate: (ctx) => {
+    if (ctx.totalWorkItems > 0) {
+      return { status: "done", evidence: ["knowledge/delivery/work-items/"] };
+    }
+    if (ctx.roadmapCandidates > 0) {
+      return { status: "current", command: "kaddo create --from roadmap", reason: "Roadmap has candidates but no Work Item exists." };
+    }
+    return { status: "pending" };
+  }
+};
+var refineWorkItem = {
+  id: "refine-work-item",
+  label: "Refine Work Item",
+  evaluate: (ctx) => {
+    if (ctx.readyWorkItems > 0 || ctx.inProgressWorkItems > 0) return { status: "done" };
+    if (ctx.draftWorkItems > 0) {
+      return {
+        status: "current",
+        reason: `There ${ctx.draftWorkItems === 1 ? "is" : "are"} ${ctx.draftWorkItems} draft Work Item${ctx.draftWorkItems === 1 ? "" : "s"} and no Work Item is ready.`,
+        agent: "work-item-agent",
+        skill: "work-item-refinement"
+      };
+    }
+    return { status: "pending" };
+  }
+};
+var suggestOwnership = {
+  id: "suggest-ownership",
+  label: "Suggest ownership",
+  evaluate: (ctx) => {
+    if (ctx.totalWorkItems === 0) return { status: "pending" };
+    if (ctx.ownershipComplete) return { status: "done" };
+    return {
+      status: "next",
+      reason: `Ownership coverage is ${ctx.ownershipCoverage}.`,
+      command: "kaddo owners suggest"
+    };
+  }
+};
+var resolveAdrs = {
+  id: "resolve-adrs",
+  label: "Resolve ADRs if needed",
+  evaluate: (ctx) => {
+    if (ctx.decisionCandidates === 0 && ctx.totalAdrs === 0) return { status: "optional" };
+    if (ctx.totalAdrs > 0) return { status: "done" };
+    return {
+      status: "warning",
+      reason: `${ctx.decisionCandidates} decision candidate(s) without ADRs.`,
+      command: "kaddo adr",
+      skill: "adr-writing"
+    };
+  }
+};
+var prepareImplementation = {
+  id: "prepare-implementation",
+  label: "Prepare implementation",
+  evaluate: (ctx) => {
+    if (ctx.inProgressWorkItems > 0 || ctx.completedWorkItems > 0) return { status: "done" };
+    if (ctx.readyWorkItems > 0) {
+      if (ctx.adaptersInstalled === 0) {
+        return { status: "current", reason: "Ready Work Items exist but no adapter is installed.", command: "kaddo adapters list" };
+      }
+      return { status: "current", agent: "implementation-agent" };
+    }
+    return { status: "pending" };
+  }
+};
+var runGuard = {
+  id: "run-guard",
+  label: "Run guard",
+  evaluate: (ctx) => {
+    if (ctx.hasGuardHistory) return { status: "done", evidence: [".kaddo/history/guard-runs.jsonl"] };
+    if (ctx.inProgressWorkItems > 0) return { status: "current", command: "kaddo guard" };
+    return { status: "pending" };
+  }
+};
+var captureLearning = {
+  id: "capture-learning",
+  label: "Capture learning",
+  evaluate: (ctx) => {
+    if (ctx.completedWorkItems > 0) return { status: "done" };
+    if (ctx.totalWorkItems === 0) return { status: "optional", reason: "Project is still in early discovery." };
+    return { status: "pending" };
+  }
+};
+var identifyLegacyModules = {
+  id: "identify-legacy-modules",
+  label: "Identify legacy modules",
+  evaluate: (ctx) => {
+    const hasLegacy = exists(join(ctx.dir, "knowledge/legacy/risks.md"));
+    return {
+      status: hasLegacy ? "done" : "pending",
+      evidence: hasLegacy ? ["knowledge/legacy/risks.md"] : void 0,
+      agent: hasLegacy ? void 0 : "legacy-agent"
+    };
+  }
+};
+var identifyRisks = {
+  id: "identify-risks",
+  label: "Identify operational risks",
+  evaluate: (ctx) => {
+    const hasLegacy = exists(join(ctx.dir, "knowledge/legacy/risks.md"));
+    return { status: hasLegacy ? "done" : "pending", agent: hasLegacy ? void 0 : "legacy-agent" };
+  }
+};
+var NEW_STEPS = [
+  enableKaddo,
+  defineBusiness,
+  defineProduct,
+  { ...discoverCapabilities, label: "Define initial capabilities" },
+  { ...describeArchitecture, label: "Define initial architecture" },
+  { ...createWorkSource, label: "Create initial work source" },
+  { ...materializeWorkItem, label: "Create first Work Item" },
+  refineWorkItem,
+  suggestOwnership,
+  prepareImplementation,
+  runGuard,
+  captureLearning
+];
+var PRE_AI_STEPS = [
+  enableKaddo,
+  scanRepository,
+  defineBusiness,
+  defineProduct,
+  discoverCapabilities,
+  describeArchitecture,
+  captureTechDecisions,
+  createWorkSource,
+  materializeWorkItem,
+  refineWorkItem,
+  suggestOwnership,
+  resolveAdrs,
+  prepareImplementation,
+  runGuard,
+  captureLearning
+];
+var LEGACY_STEPS = [
+  enableKaddo,
+  scanRepository,
+  identifyLegacyModules,
+  { ...discoverCapabilities, label: "Discover critical capabilities" },
+  describeArchitecture,
+  identifyRisks,
+  captureTechDecisions,
+  { ...createWorkSource, label: "Create modernization candidates" },
+  { ...materializeWorkItem, label: "Materialize safe Work Item" },
+  refineWorkItem,
+  suggestOwnership,
+  resolveAdrs,
+  { ...prepareImplementation, label: "Prepare safe implementation" },
+  runGuard,
+  captureLearning
+];
+function stepsForState(state) {
+  switch (state) {
+    case "new":
+      return NEW_STEPS;
+    case "legacy":
+      return LEGACY_STEPS;
+    case "pre-ai":
+    default:
+      return PRE_AI_STEPS;
+  }
+}
+function buildRouteContext(dir) {
+  const config = loadConfig(dir);
+  const hasScan = exists(join(dir, ".kaddo", "scan.json"));
+  const hasInventory = exists(join(dir, "knowledge", "inventory.md"));
+  const qa = (rel) => analyzeKnowledgeArtifact(dir, rel);
+  const wis = discoverWorkItems(dir);
+  const td = buildTechDecisions(dir);
+  const roadmapPath = join(dir, "knowledge/delivery/roadmap.md");
+  const hasRoadmap = exists(roadmapPath);
+  let roadmapMd = null;
+  if (hasRoadmap) {
+    try {
+      roadmapMd = readFile(roadmapPath);
+    } catch {
+    }
+  }
+  const stats = roadmapStats(roadmapMd, wis.length);
+  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 adapters = installedAdapters(dir);
+  const nextStep = resolveNextStep(dir);
+  return {
+    dir,
+    hasConfig: config !== null,
+    hasScan,
+    hasInventory,
+    qBusiness: qa("knowledge/business/business.md"),
+    qProduct: qa("knowledge/product/product.md"),
+    qCapabilities: qa("knowledge/product/capabilities.md"),
+    qCurrentState: qa("knowledge/tech/current-state.md"),
+    qCodebase: qa("knowledge/tech/codebase.md"),
+    hasRoadmap,
+    roadmapCandidates: stats.work_item_candidates,
+    totalWorkItems: total,
+    draftWorkItems: byState("draft"),
+    readyWorkItems: byState("ready"),
+    inProgressWorkItems: byState("in-progress"),
+    completedWorkItems: byState("completed"),
+    ownershipCoverage: `${withOwnership}/${total}`,
+    ownershipComplete: total > 0 && withOwnership >= total,
+    decisionCandidates: td.candidates,
+    acceptedAdrs: td.accepted_adrs,
+    draftAdrs: td.draft_adrs,
+    totalAdrs: td.adrs,
+    adaptersInstalled: adapters.length,
+    hasGuardHistory: exists(join(dir, ".kaddo", "history", "guard-runs.jsonl")),
+    hasScanWarnings: hasScan ? loadScanWarnings(dir) : false,
+    nextStepId: mapNextStepId(nextStep.id)
+  };
+}
+function loadScanWarnings(dir) {
+  try {
+    const parsed = JSON.parse(readFile(join(dir, ".kaddo", "scan.json")));
+    return parsed.signals ? hasWarnings(parsed.signals) : false;
+  } catch {
+    return false;
+  }
+}
+function mapNextStepId(id) {
+  const MAP = {
+    init: "enable-kaddo",
+    bootstrap: "define-business",
+    "add-agents": "enable-kaddo",
+    "add-skills": "enable-kaddo",
+    scan: "scan-repository",
+    context: "scan-repository",
+    understand: "scan-repository"
+  };
+  return MAP[id] ?? id;
+}
+function buildProjectRoute(dir) {
+  const config = loadConfig(dir);
+  const state = config?.project.state ?? "pre-ai";
+  const defs = stepsForState(state);
+  const ctx = buildRouteContext(dir);
+  const steps = defs.map((d) => {
+    const result = d.evaluate(ctx);
+    return { id: d.id, label: d.label, ...result };
+  });
+  for (const s of steps) {
+    if (s.id === ctx.nextStepId && s.status !== "done") {
+      s.status = "current";
+    }
+  }
+  let seenCurrent = false;
+  for (const s of steps) {
+    if (s.status === "current") seenCurrent = true;
+    if (seenCurrent && s.status === "pending") {
+      s.status = "next";
+      break;
+    }
+  }
+  const completed = steps.filter((s) => s.status === "done").length;
+  const total = steps.length;
+  const progressPercent = total > 0 ? Math.round(completed / total * 100) : 0;
+  return {
+    type: state,
+    currentStep: steps.find((s) => s.status === "current")?.id ?? steps.find((s) => s.status !== "done")?.id ?? "complete",
+    completed,
+    total,
+    progressPercent,
+    steps
+  };
+}
+var STATUS_MARKER = {
+  done: "[x]",
+  current: "[>]",
+  next: "[ ]",
+  pending: "[ ]",
+  optional: "[o]",
+  blocked: "[!]",
+  warning: "[~]",
+  skipped: "[-]"
+};
+function renderRouteMarkdown(route) {
+  const lines = [];
+  lines.push("## Project Route\n");
+  lines.push(`Route: ${route.type}`);
+  lines.push(`Progress: ${route.completed}/${route.total}
+`);
+  for (const s of route.steps) {
+    lines.push(`- ${STATUS_MARKER[s.status]} ${s.label}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderRouteCompact(route) {
+  const lines = [];
+  lines.push(`Route: ${route.type} \xB7 Progress: ${route.completed}/${route.total}
+`);
+  const current = route.steps.find((s) => s.status === "current");
+  if (current) {
+    const agent = current.agent ? ` \u2014 ${current.agent}` : "";
+    const skill2 = current.skill ? ` / ${current.skill}` : "";
+    lines.push(`Current:
+- ${current.label}${agent}${skill2}
+`);
+  }
+  const warnings = route.steps.filter((s) => s.status === "warning");
+  if (warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const w of warnings) {
+      lines.push(`- ${w.label}${w.reason ? ` \u2014 ${w.reason}` : ""}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
 // ../cli/src/core/project-explain.ts
 var ARCH_DIR2 = "knowledge";
 function normalizeTitle(t) {
@@ -5571,6 +6018,16 @@ function loadScan(dir) {
     return null;
   }
 }
+function loadScanSignals(dir) {
+  const scanPath = join(dir, ".kaddo", "scan.json");
+  if (!exists(scanPath)) return null;
+  try {
+    const parsed = JSON.parse(readFile(scanPath));
+    return parsed.signals ?? null;
+  } catch {
+    return null;
+  }
+}
 function hasAgents(dir) {
   const agentsDir = join(dir, ARCH_DIR2, "agents");
   if (!exists(agentsDir)) return false;
@@ -5741,7 +6198,9 @@ function buildProjectExplanation(dir) {
       }
     },
     installedAssets: installedAssetsSummary(dir),
-    roadmapQuality: buildRoadmapQuality(dir)
+    roadmapQuality: buildRoadmapQuality(dir),
+    projectRoute: buildProjectRoute(dir),
+    scanSignals: loadScanSignals(dir)
   };
 }
 function stateLabel(state) {
@@ -5786,6 +6245,10 @@ function renderExplanationHuman(exp) {
       lines.push(`- Infrastructure: ${exp.stack.infrastructureFiles.join(", ")}`);
     lines.push("");
   }
+  if (exp.scanSignals && signalCount(exp.scanSignals) > 0) {
+    lines.push("## Scan Signals");
+    lines.push(renderSignalsCompact(exp.scanSignals));
+  }
   const ls = (name) => exp.layers.find((l) => l.layer === name)?.status ?? "Missing";
   lines.push("## Knowledge Status");
   lines.push(`- Inventory: ${exp.knowledge.hasInventory ? "available" : "missing"}`);
@@ -5916,6 +6379,7 @@ function renderExplanationHuman(exp) {
     lines.push("Review before continuing (non-blocking).");
     lines.push("");
   }
+  lines.push(renderRouteMarkdown(exp.projectRoute));
   const assessment = assessPhase(exp);
   lines.push("## Phase");
   lines.push(`- Phase: ${assessment.phase}`);
@@ -7284,6 +7748,37 @@ var RESOURCES = [
       const deliveryState = { ...buildDeliveryState(root), phase: nextStepRecommendation.phase };
       return [{ uri: "kaddo://next-step", text: JSON.stringify({ nextStepRecommendation, deliveryState }, null, 2), mimeType: "application/json" }];
     }
+  },
+  {
+    uri: "kaddo://project-route",
+    name: "Kaddo project route",
+    description: "Project route progress map \u2014 where the project sits in its lifecycle (new/pre-ai/legacy), completed steps, current step, warnings (VS-080). Read-only.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://project-route", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [{ uri: "kaddo://project-route", text: JSON.stringify(buildProjectRoute(root), null, 2), mimeType: "application/json" }];
+    }
+  },
+  {
+    uri: "kaddo://scan-signals",
+    name: "Kaddo scan signals",
+    description: "Actionable signals detected by `kaddo scan`: auth, payments, webhooks, storage, background jobs, email, database, migrations, API routes, tests, security, infrastructure, integrations, environment (VS-081). Read-only.",
+    mimeType: "application/json",
+    read: (root) => {
+      const body = readText(root, ".kaddo/scan.json");
+      if (body) {
+        try {
+          const parsed = JSON.parse(body);
+          if (parsed.signals) {
+            return [{ uri: "kaddo://scan-signals", text: JSON.stringify(parsed.signals, null, 2), mimeType: "application/json" }];
+          }
+        } catch {
+        }
+      }
+      return text("kaddo://scan-signals", "Scan signals not found. Run `kaddo scan` first.", "text/plain");
+    }
   }
 ];
 
@@ -7625,6 +8120,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
     skills: discoverInstalledSkills(dir).map((s) => s.id),
+    scanSignals: scanJson?.signals ?? null,
+    projectRoute: buildProjectRoute(dir),
     mappedModules,
     missing,
     // VS-052/VS-073.2: the handoff is driven by the unified next step, so the pack never contradicts
@@ -7701,6 +8198,8 @@ function renderContextPack(pack) {
       parts.push(rec.secondary.map((s) => `- ${s.label}`).join("\n") + "\n");
     }
   }
+  parts.push("## Project Route\n");
+  parts.push(renderRouteCompact(pack.projectRoute));
   parts.push("## Knowledge Layers\n");
   parts.push(
     "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
@@ -7736,6 +8235,10 @@ function renderContextPack(pack) {
   } else {
     parts.push("Scan baseline missing. Run `kaddo scan` for better context.\n");
   }
+  if (pack.scanSignals && signalCount(pack.scanSignals) > 0) {
+    parts.push("## Scan Signals\n");
+    parts.push(renderSignalsCompact(pack.scanSignals));
+  }
   parts.push("## Current Knowledge\n");
   parts.push((knowledge.summary || "No project knowledge summary found yet.") + "\n");
   parts.push("## Roadmap Status\n");
@@ -8008,6 +8511,10 @@ function renderUnderstand(plan) {
       ].join("\n") + "\n"
     );
   }
+  if (plan.projectRoute) {
+    parts.push("## Project Route\n");
+    parts.push(renderRouteCompact(plan.projectRoute));
+  }
   if (steps.length > 0) {
     parts.push("## Recommended Agent Flow\n");
     parts.push(`Recommended order for a ${stateLabel2(project.state)} project:

package/package.json

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