@kaddo/cli 3.46.0 → 3.48.0

package/dist/index.js

@@ -239,6 +239,552 @@ async function runInit() {
   outro2("Kaddo initialized.");
 }
 
+// src/core/scan-signals.ts
+function emptySignals() {
+  return {
+    auth: [],
+    payments: [],
+    webhooks: [],
+    storage: [],
+    background_jobs: [],
+    email: [],
+    database: [],
+    migrations: [],
+    api_routes: [],
+    tests: [],
+    security: [],
+    infrastructure: [],
+    external_integrations: [],
+    environment: []
+  };
+}
+function sig(type, label, confidence, evidence, extra) {
+  return { type, label, confidence, evidence, ...extra };
+}
+function readDeps(dir) {
+  const pkgPath = join(dir, "package.json");
+  if (!exists(pkgPath)) return {};
+  try {
+    const pkg = JSON.parse(readFile(pkgPath));
+    return { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  } catch {
+    return {};
+  }
+}
+function findFilesMatching(dir, codeDirs, pattern, maxDepth = 3) {
+  const found = [];
+  const walk = (base, rel, depth) => {
+    if (depth > maxDepth) return;
+    try {
+      const entries = readDir(join(base, rel));
+      for (const e of entries) {
+        if (e.startsWith(".") || e === "node_modules" || e === "dist" || e === "build" || e === ".next") continue;
+        const fullRel = rel ? `${rel}/${e}` : e;
+        if (isDir(join(base, fullRel))) {
+          walk(base, fullRel, depth + 1);
+        } else if (pattern.test(e)) {
+          found.push(fullRel);
+        }
+      }
+    } catch {
+    }
+  };
+  for (const cd of codeDirs) {
+    walk(dir, cd, 0);
+  }
+  return found;
+}
+function findPathsContaining(dir, codeDirs, keywords, maxDepth = 3) {
+  const found = [];
+  const walk = (base, rel, depth) => {
+    if (depth > maxDepth) return;
+    try {
+      const entries = readDir(join(base, rel));
+      for (const e of entries) {
+        if (e.startsWith(".") || e === "node_modules" || e === "dist" || e === "build" || e === ".next") continue;
+        const fullRel = rel ? `${rel}/${e}` : e;
+        const lower = e.toLowerCase();
+        if (keywords.some((k) => lower.includes(k))) {
+          found.push(fullRel);
+        }
+        if (isDir(join(base, fullRel))) {
+          walk(base, fullRel, depth + 1);
+        }
+      }
+    } catch {
+    }
+  };
+  for (const cd of codeDirs) {
+    walk(dir, cd, 0);
+  }
+  return found;
+}
+function detectAuth(dir, deps, codeDirs, signals) {
+  const authDeps = [
+    ["next-auth", "NextAuth"],
+    ["@auth/core", "Auth.js"],
+    ["@supabase/supabase-js", "Supabase Auth"],
+    ["@supabase/auth-helpers-nextjs", "Supabase Auth"],
+    ["@supabase/ssr", "Supabase Auth"],
+    ["@clerk/nextjs", "Clerk"],
+    ["@clerk/clerk-sdk-node", "Clerk"],
+    ["firebase", "Firebase Auth"],
+    ["firebase-admin", "Firebase Auth"],
+    ["passport", "Passport.js"],
+    ["jsonwebtoken", "JWT"],
+    ["jose", "JWT (jose)"],
+    ["bcrypt", "Password hashing (bcrypt)"],
+    ["bcryptjs", "Password hashing (bcryptjs)"],
+    ["@aws-amplify/auth", "AWS Amplify Auth"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [dep, label] of authDeps) {
+    if (dep in deps && !seen.has(label)) {
+      seen.add(label);
+      signals.auth.push(sig("auth", label, "high", ["package.json"]));
+    }
+  }
+  const authPaths = findPathsContaining(dir, codeDirs, ["auth", "login", "register", "signin", "signup", "session"], 3);
+  if (authPaths.length > 0 && signals.auth.length === 0) {
+    signals.auth.push(sig("auth", "Auth-related paths detected", "medium", authPaths.slice(0, 5)));
+  }
+}
+function detectPayments(dir, deps, codeDirs, signals) {
+  const payDeps = [
+    ["stripe", "Stripe"],
+    ["@stripe/stripe-js", "Stripe"],
+    ["mercadopago", "Mercado Pago"],
+    ["@paypal/checkout-server-sdk", "PayPal"],
+    ["paypal-rest-sdk", "PayPal"],
+    ["wompi", "Wompi"],
+    ["@adyen/api-library", "Adyen"],
+    ["braintree", "Braintree"],
+    ["square", "Square"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [dep, label] of payDeps) {
+    if (dep in deps && !seen.has(label)) {
+      seen.add(label);
+      signals.payments.push(sig("payments", label, "high", ["package.json"]));
+    }
+  }
+  const payPaths = findPathsContaining(dir, codeDirs, ["payment", "checkout", "billing", "invoice", "subscription", "pricing"], 3);
+  if (payPaths.length > 0 && signals.payments.length === 0) {
+    signals.payments.push(sig("payments", "Payment-related paths detected", "medium", payPaths.slice(0, 5)));
+  }
+}
+function detectWebhooks(dir, codeDirs, signals) {
+  const whPaths = findPathsContaining(dir, codeDirs, ["webhook", "callback"], 3);
+  if (whPaths.length > 0) {
+    signals.webhooks.push(sig("webhooks", "Webhook routes detected", "high", whPaths.slice(0, 5), {
+      recommended_review: "Verify idempotency and signature validation."
+    }));
+  }
+}
+function detectStorage(dir, deps, codeDirs, signals) {
+  const storageDeps = [
+    ["@aws-sdk/client-s3", "AWS S3"],
+    ["aws-sdk", "AWS SDK (includes S3)"],
+    ["@supabase/storage-js", "Supabase Storage"],
+    ["cloudinary", "Cloudinary"],
+    ["multer", "File upload (Multer)"],
+    ["formidable", "File upload (Formidable)"],
+    ["@google-cloud/storage", "Google Cloud Storage"],
+    ["@azure/storage-blob", "Azure Blob Storage"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [dep, label] of storageDeps) {
+    if (dep in deps && !seen.has(label)) {
+      seen.add(label);
+      signals.storage.push(sig("storage", label, "high", ["package.json"]));
+    }
+  }
+  const storagePaths = findPathsContaining(dir, codeDirs, ["upload", "storage", "bucket"], 3);
+  if (storagePaths.length > 0 && signals.storage.length === 0) {
+    signals.storage.push(sig("storage", "Storage-related paths detected", "medium", storagePaths.slice(0, 5)));
+  }
+}
+function detectBackgroundJobs(dir, deps, codeDirs, signals) {
+  const jobDeps = [
+    ["bullmq", "BullMQ"],
+    ["bull", "Bull"],
+    ["agenda", "Agenda"],
+    ["@aws-sdk/client-sqs", "AWS SQS"],
+    ["amqplib", "RabbitMQ (AMQP)"],
+    ["bee-queue", "Bee-Queue"],
+    ["node-cron", "Node-cron"],
+    ["cron", "Cron"]
+  ];
+  for (const [dep, label] of jobDeps) {
+    if (dep in deps) {
+      signals.background_jobs.push(sig("background_jobs", label, "high", ["package.json"]));
+    }
+  }
+  if (isDir(join(dir, "supabase", "functions"))) {
+    signals.background_jobs.push(sig("background_jobs", "Supabase Edge Functions", "high", ["supabase/functions/"]));
+  }
+  const cronMigrations = findFilesMatching(dir, ["supabase/migrations"], /pg_cron|cron/i, 2);
+  if (cronMigrations.length > 0) {
+    signals.background_jobs.push(sig("background_jobs", "pg_cron scheduled jobs", "high", cronMigrations.slice(0, 3)));
+  }
+  if (exists(join(dir, "vercel.json"))) {
+    try {
+      const vc = JSON.parse(readFile(join(dir, "vercel.json")));
+      if (vc.crons && Array.isArray(vc.crons) && vc.crons.length > 0) {
+        signals.background_jobs.push(sig("background_jobs", "Vercel Cron Jobs", "high", ["vercel.json"]));
+      }
+    } catch {
+    }
+  }
+  const jobPaths = findPathsContaining(dir, codeDirs, ["cron", "queue", "worker", "job"], 3);
+  if (jobPaths.length > 0 && signals.background_jobs.length === 0) {
+    signals.background_jobs.push(sig("background_jobs", "Job-related paths detected", "medium", jobPaths.slice(0, 5)));
+  }
+}
+function detectEmail(dir, deps, signals) {
+  const emailDeps = [
+    ["resend", "Resend"],
+    ["@sendgrid/mail", "SendGrid"],
+    ["@sendinblue/client", "Brevo (Sendinblue)"],
+    ["@getbrevo/brevo", "Brevo"],
+    ["nodemailer", "Nodemailer"],
+    ["@aws-sdk/client-ses", "AWS SES"],
+    ["postmark", "Postmark"],
+    ["mailgun-js", "Mailgun"],
+    ["@mailchimp/mailchimp_transactional", "Mailchimp Transactional"]
+  ];
+  for (const [dep, label] of emailDeps) {
+    if (dep in deps) {
+      signals.email.push(sig("email", label, "high", ["package.json"]));
+    }
+  }
+}
+function detectDatabase(dir, deps, signals) {
+  const dbDeps = [
+    ["prisma", "Prisma"],
+    ["@prisma/client", "Prisma"],
+    ["drizzle-orm", "Drizzle ORM"],
+    ["typeorm", "TypeORM"],
+    ["sequelize", "Sequelize"],
+    ["knex", "Knex.js"],
+    ["@supabase/supabase-js", "Supabase (Postgres)"],
+    ["pg", "PostgreSQL (pg)"],
+    ["mysql2", "MySQL"],
+    ["mongodb", "MongoDB"],
+    ["mongoose", "Mongoose (MongoDB)"],
+    ["better-sqlite3", "SQLite"],
+    ["@neondatabase/serverless", "Neon Postgres"],
+    ["@planetscale/database", "PlanetScale"],
+    ["@libsql/client", "Turso (LibSQL)"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [dep, label] of dbDeps) {
+    if (dep in deps && !seen.has(label)) {
+      seen.add(label);
+      signals.database.push(sig("database", label, "high", ["package.json"]));
+    }
+  }
+}
+function detectMigrations(dir, migrationDirs, signals) {
+  for (const md of migrationDirs) {
+    const fullPath = join(dir, md);
+    if (!isDir(fullPath)) continue;
+    let count = 0;
+    try {
+      count = readDir(fullPath).filter((f) => !f.startsWith(".")).length;
+    } catch {
+    }
+    signals.migrations.push(sig("migrations", `${md} (${count} file${count === 1 ? "" : "s"})`, "high", [md]));
+  }
+}
+function detectApiRoutes(dir, codeDirs, signals) {
+  for (const cd of codeDirs) {
+    const apiDir = join(dir, cd, "app", "api");
+    if (isDir(apiDir)) {
+      signals.api_routes.push(sig("api_routes", "Next.js API routes", "high", [`${cd}/app/api`]));
+    }
+    const pagesApi = join(dir, cd, "pages", "api");
+    if (isDir(pagesApi)) {
+      signals.api_routes.push(sig("api_routes", "Next.js Pages API routes", "high", [`${cd}/pages/api`]));
+    }
+  }
+  if (isDir(join(dir, "app", "api"))) {
+    signals.api_routes.push(sig("api_routes", "Next.js API routes", "high", ["app/api"]));
+  }
+  if (isDir(join(dir, "pages", "api"))) {
+    signals.api_routes.push(sig("api_routes", "Next.js Pages API routes", "high", ["pages/api"]));
+  }
+  if (isDir(join(dir, "routes"))) {
+    signals.api_routes.push(sig("api_routes", "Routes directory", "medium", ["routes/"]));
+  }
+}
+function detectTests(dir, testDirs, deps, signals) {
+  const testFrameworks = [
+    ["vitest", "Vitest"],
+    ["jest", "Jest"],
+    ["@playwright/test", "Playwright"],
+    ["cypress", "Cypress"],
+    ["@testing-library/react", "Testing Library"],
+    ["mocha", "Mocha"],
+    ["ava", "AVA"]
+  ];
+  for (const [dep, label] of testFrameworks) {
+    if (dep in deps) {
+      signals.tests.push(sig("tests", label, "high", ["package.json"]));
+    }
+  }
+  if (testDirs.length > 0) {
+    signals.tests.push(sig("tests", `Test directories: ${testDirs.join(", ")}`, "high", testDirs));
+  }
+  if (testDirs.length === 0 && signals.tests.length === 0) {
+    signals.tests.push(sig("tests", "No test directory detected", "high", [], {
+      recommended_review: "Confirm how this project is validated before production changes."
+    }));
+  }
+}
+function detectSecurity(dir, deps, codeDirs, envVarNames, signals) {
+  const secDeps = [
+    ["helmet", "Helmet (security headers)"],
+    ["cors", "CORS middleware"],
+    ["csurf", "CSRF protection"],
+    ["express-rate-limit", "Rate limiting"],
+    ["@upstash/ratelimit", "Upstash Rate Limiting"]
+  ];
+  for (const [dep, label] of secDeps) {
+    if (dep in deps) {
+      signals.security.push(sig("security", label, "high", ["package.json"]));
+    }
+  }
+  const middlewarePaths = findPathsContaining(dir, codeDirs, ["middleware"], 2);
+  if (middlewarePaths.length > 0) {
+    signals.security.push(sig("security", "Middleware detected", "medium", middlewarePaths.slice(0, 5)));
+  }
+  if (isFile(join(dir, "middleware.ts")) || isFile(join(dir, "middleware.js")) || isFile(join(dir, "src", "middleware.ts")) || isFile(join(dir, "src", "middleware.js"))) {
+    const evidence = ["middleware.ts", "middleware.js", "src/middleware.ts", "src/middleware.js"].filter((f) => isFile(join(dir, f)));
+    if (evidence.length > 0) {
+      signals.security.push(sig("security", "Next.js middleware", "high", evidence));
+    }
+  }
+  const rlsMigrations = findFilesMatching(dir, ["supabase/migrations"], /rls|policies|policy/i, 2);
+  if (rlsMigrations.length > 0) {
+    signals.security.push(sig("security", "RLS / row-level security policies", "high", rlsMigrations.slice(0, 3)));
+  }
+  const secretVars = envVarNames.filter((v) => /secret|token|key|password|credential/i.test(v));
+  if (secretVars.length > 0) {
+    signals.security.push(sig("security", "Secret-bearing environment variables", "medium", secretVars.slice(0, 10), {
+      recommended_review: "Confirm secret rotation and endpoint protection strategy."
+    }));
+  }
+}
+function detectInfrastructure(dir, infraFiles, signals) {
+  for (const f of infraFiles) {
+    const label = inferInfraLabel(f);
+    signals.infrastructure.push(sig("infrastructure", label, "high", [f]));
+  }
+}
+function inferInfraLabel(f) {
+  const lower = f.toLowerCase();
+  if (lower.includes("docker-compose")) return "Docker Compose";
+  if (lower === "dockerfile") return "Dockerfile";
+  if (lower.includes("serverless")) return "Serverless Framework";
+  if (lower.includes("amplify")) return "AWS Amplify";
+  if (lower.includes("terraform")) return "Terraform";
+  if (lower.includes("k8s") || lower.includes("kubernetes")) return "Kubernetes";
+  if (lower.includes("helm")) return "Helm";
+  if (lower.includes(".github/workflows")) return "GitHub Actions";
+  if (lower.includes("vercel")) return "Vercel";
+  if (lower.includes("netlify")) return "Netlify";
+  return f;
+}
+function detectExternalIntegrations(deps, signals) {
+  const integrations = [
+    ["@supabase/supabase-js", "Supabase"],
+    ["@aws-sdk/client-s3", "AWS"],
+    ["aws-sdk", "AWS"],
+    ["@google-cloud/storage", "Google Cloud"],
+    ["@azure/storage-blob", "Azure"],
+    ["twilio", "Twilio"],
+    ["@slack/web-api", "Slack"],
+    ["@slack/bolt", "Slack"],
+    ["@notionhq/client", "Notion"],
+    ["@octokit/rest", "GitHub API"],
+    ["@sentry/node", "Sentry"],
+    ["@sentry/nextjs", "Sentry"],
+    ["@datadog/datadog-api-client", "Datadog"],
+    ["newrelic", "New Relic"],
+    ["@segment/analytics-node", "Segment"],
+    ["posthog-node", "PostHog"],
+    ["mixpanel", "Mixpanel"],
+    ["@amplitude/node", "Amplitude"],
+    ["firebase-admin", "Firebase"],
+    ["@google/generative-ai", "Google AI"],
+    ["openai", "OpenAI"],
+    ["@anthropic-ai/sdk", "Anthropic"],
+    ["@vercel/analytics", "Vercel Analytics"],
+    ["@vercel/kv", "Vercel KV"],
+    ["@upstash/redis", "Upstash Redis"],
+    ["ioredis", "Redis"]
+  ];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [dep, label] of integrations) {
+    if (dep in deps && !seen.has(label)) {
+      seen.add(label);
+      signals.external_integrations.push(sig("external_integrations", label, "high", ["package.json"]));
+    }
+  }
+}
+function detectEnvironment(dir) {
+  const envFiles = [".env.example", ".env.local.example", ".env.template", ".env.sample"];
+  const varNames = /* @__PURE__ */ new Set();
+  for (const ef of envFiles) {
+    const p2 = join(dir, ef);
+    if (!exists(p2)) continue;
+    try {
+      const lines = readFile(p2).split(/\r?\n/);
+      for (const line of lines) {
+        const m = line.match(/^([A-Z][A-Z0-9_]+)\s*=/);
+        if (m) varNames.add(m[1]);
+      }
+    } catch {
+    }
+  }
+  const envPath = join(dir, ".env");
+  if (exists(envPath)) {
+    try {
+      const lines = readFile(envPath).split(/\r?\n/);
+      for (const line of lines) {
+        const m = line.match(/^([A-Z][A-Z0-9_]+)\s*=/);
+        if (m) varNames.add(m[1]);
+      }
+    } catch {
+    }
+  }
+  return [...varNames].sort();
+}
+function buildScanSignals(dir, codeDirs, migrationDirs, testDirs, infraFiles) {
+  const signals = emptySignals();
+  const deps = readDeps(dir);
+  const envVarNames = detectEnvironment(dir);
+  detectAuth(dir, deps, codeDirs, signals);
+  detectPayments(dir, deps, codeDirs, signals);
+  detectWebhooks(dir, codeDirs, signals);
+  detectStorage(dir, deps, codeDirs, signals);
+  detectBackgroundJobs(dir, deps, codeDirs, signals);
+  detectEmail(dir, deps, signals);
+  detectDatabase(dir, deps, signals);
+  detectMigrations(dir, migrationDirs, signals);
+  detectApiRoutes(dir, codeDirs, signals);
+  detectTests(dir, testDirs, deps, signals);
+  detectSecurity(dir, deps, codeDirs, envVarNames, signals);
+  detectInfrastructure(dir, infraFiles, signals);
+  detectExternalIntegrations(deps, signals);
+  if (envVarNames.length > 0) {
+    signals.environment.push(sig("environment", `${envVarNames.length} environment variable(s) detected`, "high", envVarNames.slice(0, 20)));
+  }
+  return signals;
+}
+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";
+}
+function renderSignalsInventory(signals) {
+  const parts = [];
+  const CATEGORIES = [
+    ["auth", "Auth"],
+    ["payments", "Payments"],
+    ["webhooks", "Webhooks"],
+    ["storage", "Storage"],
+    ["background_jobs", "Background Jobs"],
+    ["email", "Email / Notifications"],
+    ["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;
+    parts.push(`### ${label}
+`);
+    for (const s of arr) {
+      parts.push(`- ${s.label} \u2014 confidence: ${s.confidence}`);
+      if (s.evidence.length > 0) {
+        parts.push(`  - Evidence: ${s.evidence.map((e) => "`" + e + "`").join(", ")}`);
+      }
+      if (s.recommended_review) {
+        parts.push(`  - Review: ${s.recommended_review}`);
+      }
+    }
+    parts.push("");
+  }
+  return parts.join("\n");
+}
+function renderSignalsConsole(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", "Integrations"],
+    ["environment", "Environment"]
+  ];
+  for (const [key, label] of CATEGORIES) {
+    const arr = signals[key];
+    if (arr.length === 0) continue;
+    if (arr.length === 1) {
+      const warning = arr[0].label.toLowerCase().includes("no test") ? " \u26A0" : "";
+      lines.push(`  ${label}: ${arr[0].label}${warning}`);
+    } else {
+      lines.push(`  ${label}: ${arr.map((s) => s.label).join(", ")}`);
+    }
+  }
+  return lines;
+}
+
 // src/services/scanner.ts
 function detectLanguage(dir) {
   if (exists(join(dir, "tsconfig.json"))) return "typescript";
@@ -391,6 +937,7 @@ function scan(dir) {
   const testDirs = detectTestDirs(dir);
   const hasGit2 = isDir(join(dir, ".git"));
   const suggestedDomains = suggestDomains(dir, codeDirs);
+  const signals = buildScanSignals(dir, codeDirs, migrationDirs, testDirs, infraFiles);
   return {
     language,
     framework,
@@ -401,7 +948,8 @@ function scan(dir) {
     infraFiles,
     testDirs,
     hasGit: hasGit2,
-    suggestedDomains
+    suggestedDomains,
+    signals
   };
 }
 
@@ -465,6 +1013,7 @@ function buildBaseline(result, context, now = /* @__PURE__ */ new Date()) {
       infrastructureFiles: result.infraFiles,
       testDirectories: result.testDirs
     },
+    signals: result.signals,
     suggestions: {
       possibleDomains: result.suggestedDomains.map((d) => d.replace(/^#\s*/, "").trim()).filter(Boolean),
       openQuestions: buildOpenQuestions(result, context)
@@ -509,6 +1058,10 @@ function renderInventory(baseline) {
   parts.push(section("Contracts", detected.contractFiles));
   parts.push(section("Infrastructure", detected.infrastructureFiles));
   parts.push(section("Tests", detected.testDirectories.map((d) => `${d}/`)));
+  if (signalCount(baseline.signals) > 0) {
+    parts.push("## Detected Signals\n");
+    parts.push(renderSignalsInventory(baseline.signals));
+  }
   parts.push(section("Possible Domains", suggestions.possibleDomains));
   parts.push(section("Open Questions", suggestions.openQuestions));
   return parts.join("\n");
@@ -766,7 +1319,15 @@ function printResult(result) {
     console.log("No domains detected automatically.");
     console.log("You can add them manually in .kaddo/config.yml under project.domains.");
   }
-  console.log("");
+  const signalLines = renderSignalsConsole(result.signals);
+  if (signalLines.length > 0) {
+    console.log("Signals:");
+    for (const line of signalLines) console.log(line);
+    console.log("");
+  } else {
+    console.log("Signals: none detected");
+    console.log("");
+  }
 }
 function updateConfig(dir, result) {
   const configPath = join(dir, ".kaddo", "config.yml");
@@ -4641,8 +5202,8 @@ function parseBlock(block) {
 }
 function decisionCandidatesFromSignals(signals) {
   const out = [];
-  for (const sig of signals) {
-    const m = sig.match(/decision candidate\s*:?\s*(.+)$/i);
+  for (const sig2 of signals) {
+    const m = sig2.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/);
@@ -8680,6 +9241,416 @@ function buildRoadmapQuality(dir) {
   return { initiatives, work_item_candidates };
 }
 
+// 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 runGuard2 = {
+  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,
+  runGuard2,
+  captureLearning
+];
+var PRE_AI_STEPS = [
+  enableKaddo,
+  scanRepository,
+  defineBusiness,
+  defineProduct,
+  discoverCapabilities,
+  describeArchitecture,
+  captureTechDecisions,
+  createWorkSource,
+  materializeWorkItem,
+  refineWorkItem,
+  suggestOwnership,
+  resolveAdrs,
+  prepareImplementation,
+  runGuard2,
+  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" },
+  runGuard2,
+  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");
+}
+
 // src/core/project-explain.ts
 var ARCH_DIR4 = "knowledge";
 function normalizeTitle(t) {
@@ -8735,6 +9706,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_DIR4, "agents");
   if (!exists(agentsDir)) return false;
@@ -8905,7 +9886,9 @@ function buildProjectExplanation(dir) {
       }
     },
     installedAssets: installedAssetsSummary(dir),
-    roadmapQuality: buildRoadmapQuality(dir)
+    roadmapQuality: buildRoadmapQuality(dir),
+    projectRoute: buildProjectRoute(dir),
+    scanSignals: loadScanSignals(dir)
   };
 }
 function stateLabel(state) {
@@ -8950,6 +9933,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"}`);
@@ -9080,6 +10067,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}`);
@@ -9614,6 +10602,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
@@ -9690,6 +10680,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"
@@ -9725,6 +10717,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");
@@ -9994,7 +10990,8 @@ function enrichUnderstandPlan(plan, opts) {
     deliveryState: opts.deliveryState,
     activeWorkItems: opts.activeWorkItems,
     recommendedPaths: opts.recommendedPaths,
-    recommendedSkillPaths: opts.recommendedSkillPaths
+    recommendedSkillPaths: opts.recommendedSkillPaths,
+    projectRoute: opts.projectRoute
   };
 }
 
@@ -10048,6 +11045,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:
@@ -10433,7 +11434,8 @@ function runUnderstand() {
     activeWorkItems: activeWis,
     recommendedPaths,
     recommendedSkillPaths,
-    language: languageLabel(projectLanguage(config))
+    language: languageLabel(projectLanguage(config)),
+    projectRoute: buildProjectRoute(dir)
   });
   writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(enrichedPlan));
   log2.success("Wrote .kaddo/understand.md");
@@ -11090,7 +12092,7 @@ function findWorkItemArtifacts(dir) {
 function artifactsMissingOwnership(artifacts) {
   return artifacts.filter((a) => !a.hasOwnership);
 }
-function loadScanSignals(dir) {
+function loadScanSignals2(dir) {
   const scanPath = join(dir, SCAN_PATH);
   if (!exists(scanPath)) return null;
   try {
@@ -11268,7 +12270,7 @@ async function runOwnersSuggest() {
     }))
   });
   const artifact = missing.find((a) => a.relPath === relPath);
-  const signals = loadScanSignals(dir);
+  const signals = loadScanSignals2(dir);
   if (!signals) {
     log2.warn("No .kaddo/scan.json found \u2014 run `kaddo scan` for suggestions. You can enter globs manually.");
   }

package/package.json

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