@thanh01.pmt/domain-kit 0.1.0

package/dist/pipeline/index.cjs

@@ -0,0 +1,2166 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var child_process = require('child_process');
+
+// src/parsers/swift.ts
+var IMPORT_RE = /^import\s+(\w+)/gm;
+var TYPE_RE = /\b(class|struct|enum|protocol)\s+(\w+)(?:\s*:\s*([^{]+))?/g;
+var FUNC_RE = /\bfunc\s+(\w+)\s*\(([^)]*)\)(?:\s*->\s*([^{]+))?/g;
+var WRAPPER_RE = /@(State|Binding|ObservedObject|StateObject|Published|Environment|EnvironmentObject|AppStorage|SceneStorage|FocusState|Observable)\b/g;
+var FRAMEWORK_USAGE_RE = /\b(URLSession|URLRequest|JSONSerialization|JSONDecoder|JSONEncoder|Task|DispatchQueue|Timer|NotificationCenter|UserDefaults|FileManager|Bundle)\b/g;
+function parseSwiftFile(filepath, content) {
+  const result = {
+    imports: [],
+    types: [],
+    functions: [],
+    property_wrappers: [],
+    error_handling: [],
+    frameworks_used: []
+  };
+  let match;
+  while ((match = IMPORT_RE.exec(content)) !== null) {
+    result.imports.push(match[1]);
+  }
+  const fwSeen = /* @__PURE__ */ new Set();
+  while ((match = FRAMEWORK_USAGE_RE.exec(content)) !== null) {
+    if (!fwSeen.has(match[1])) {
+      fwSeen.add(match[1]);
+      result.frameworks_used.push(match[1]);
+    }
+  }
+  while ((match = TYPE_RE.exec(content)) !== null) {
+    const conforms = (match[3] || "").split(",").map((p) => p.trim()).filter(Boolean);
+    result.types.push({
+      kind: match[1],
+      name: match[2],
+      conforms_to: conforms,
+      file: filepath
+    });
+  }
+  while ((match = FUNC_RE.exec(content)) !== null) {
+    const name = match[1];
+    if (name.startsWith("_")) continue;
+    result.functions.push({
+      name,
+      params: (match[2] || "").trim(),
+      returns: (match[3] || "").trim(),
+      file: filepath
+    });
+  }
+  const wrapperSet = /* @__PURE__ */ new Set();
+  while ((match = WRAPPER_RE.exec(content)) !== null) {
+    wrapperSet.add(match[1]);
+  }
+  result.property_wrappers = Array.from(wrapperSet);
+  if (content.includes("do {") || content.includes("do{")) {
+    result.error_handling.push("do-catch");
+  }
+  if (content.includes("throws")) {
+    result.error_handling.push("throws");
+  }
+  if (content.includes("Result<")) {
+    result.error_handling.push("Result type");
+  }
+  if (content.includes("try?")) {
+    result.error_handling.push("try?");
+  }
+  if (content.includes("try!")) {
+    result.error_handling.push("try!");
+  }
+  return result;
+}
+function mergeSwiftResults(results) {
+  const merged = {
+    imports: [],
+    types: [],
+    functions: [],
+    property_wrappers: [],
+    error_handling: [],
+    frameworks_used: []
+  };
+  const importCounts = /* @__PURE__ */ new Map();
+  const wrapperCounts = /* @__PURE__ */ new Map();
+  const errorCounts = /* @__PURE__ */ new Map();
+  const frameworkSet = /* @__PURE__ */ new Set();
+  for (const r of results) {
+    for (const imp of r.imports) {
+      importCounts.set(imp, (importCounts.get(imp) || 0) + 1);
+    }
+    merged.types.push(...r.types);
+    merged.functions.push(...r.functions);
+    for (const w of r.property_wrappers) {
+      wrapperCounts.set(w, (wrapperCounts.get(w) || 0) + 1);
+    }
+    for (const e of r.error_handling) {
+      errorCounts.set(e, (errorCounts.get(e) || 0) + 1);
+    }
+    for (const fw of r.frameworks_used) {
+      frameworkSet.add(fw);
+    }
+  }
+  merged.imports = Array.from(importCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([mod, count]) => mod);
+  merged.property_wrappers = Array.from(wrapperCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([w]) => w);
+  merged.error_handling = Array.from(errorCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([p]) => p);
+  merged.frameworks_used = Array.from(frameworkSet).sort();
+  merged.types = merged.types.slice(0, 100);
+  merged.functions = merged.functions.slice(0, 100);
+  return merged;
+}
+
+// src/parsers/typescript.ts
+var IMPORT_RE2 = /import\s+.*?from\s+['"]([^'"]+)['"]/g;
+var TYPE_RE2 = /\b(interface|type|class|enum)\s+(\w+)/g;
+var FUNC_RE2 = /\bfunction\s+(\w+)\s*\(([^)]*)\)/g;
+var ARROW_RE = /\bconst\s+(\w+)\s*=\s*\([^)]*\)\s*(?::\s*\w+)?\s*=>/g;
+function parseTsFile(filepath, content) {
+  const result = {
+    imports: [],
+    types: [],
+    functions: [],
+    error_handling: []
+  };
+  let match;
+  while ((match = IMPORT_RE2.exec(content)) !== null) {
+    result.imports.push(match[1]);
+  }
+  while ((match = TYPE_RE2.exec(content)) !== null) {
+    result.types.push({
+      kind: match[1],
+      name: match[2],
+      file: filepath
+    });
+  }
+  while ((match = FUNC_RE2.exec(content)) !== null) {
+    result.functions.push({
+      name: match[1],
+      params: (match[2] || "").trim(),
+      file: filepath
+    });
+  }
+  while ((match = ARROW_RE.exec(content)) !== null) {
+    result.functions.push({
+      name: match[1],
+      params: "",
+      file: filepath
+    });
+  }
+  if (content.includes("try {") || content.includes("try{")) {
+    result.error_handling.push("try-catch");
+  }
+  if (content.includes("Promise")) {
+    result.error_handling.push("Promise");
+  }
+  if (content.includes(".catch(")) {
+    result.error_handling.push(".catch()");
+  }
+  return result;
+}
+function mergeTsResults(results) {
+  const merged = {
+    imports: [],
+    types: [],
+    functions: [],
+    error_handling: []
+  };
+  const importCounts = /* @__PURE__ */ new Map();
+  const errorCounts = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    for (const imp of r.imports) {
+      importCounts.set(imp, (importCounts.get(imp) || 0) + 1);
+    }
+    merged.types.push(...r.types);
+    merged.functions.push(...r.functions);
+    for (const e of r.error_handling) {
+      errorCounts.set(e, (errorCounts.get(e) || 0) + 1);
+    }
+  }
+  merged.imports = Array.from(importCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([mod]) => mod);
+  merged.error_handling = Array.from(errorCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([p]) => p);
+  merged.types = merged.types.slice(0, 100);
+  merged.functions = merged.functions.slice(0, 100);
+  return merged;
+}
+
+// src/parsers/python.ts
+var IMPORT_RE3 = /^(?:import|from)\s+(\w+)/gm;
+var CLASS_RE = /\bclass\s+(\w+)(?:\s*\(([^)]+)\))?/g;
+var FUNC_RE3 = /\bdef\s+(\w+)\s*\(([^)]*)\)/g;
+var DOCSTRING_RE = /"""([^"]{20,300})"""/g;
+function parsePythonFile(filepath, content) {
+  const result = {
+    imports: [],
+    types: [],
+    functions: [],
+    docstrings: [],
+    error_handling: []
+  };
+  let match;
+  while ((match = IMPORT_RE3.exec(content)) !== null) {
+    result.imports.push(match[1]);
+  }
+  while ((match = DOCSTRING_RE.exec(content)) !== null) {
+    const firstSentence = match[1].trim().split("\n")[0].slice(0, 120);
+    if (firstSentence.length > 15) {
+      result.docstrings.push(firstSentence);
+    }
+  }
+  while ((match = CLASS_RE.exec(content)) !== null) {
+    const bases = (match[2] || "").split(",").map((b) => b.trim()).filter(Boolean);
+    result.types.push({
+      kind: "class",
+      name: match[1],
+      bases,
+      file: filepath
+    });
+  }
+  while ((match = FUNC_RE3.exec(content)) !== null) {
+    const name = match[1];
+    if (name.startsWith("__") && name.endsWith("__")) continue;
+    result.functions.push({
+      name,
+      params: (match[2] || "").trim(),
+      file: filepath
+    });
+  }
+  if (content.includes("try:")) {
+    result.error_handling.push("try-except");
+  }
+  if (content.includes("raise")) {
+    result.error_handling.push("raise");
+  }
+  return result;
+}
+function mergePythonResults(results) {
+  const merged = {
+    imports: [],
+    types: [],
+    functions: [],
+    docstrings: [],
+    error_handling: []
+  };
+  const importCounts = /* @__PURE__ */ new Map();
+  const errorCounts = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    for (const imp of r.imports) {
+      importCounts.set(imp, (importCounts.get(imp) || 0) + 1);
+    }
+    merged.types.push(...r.types);
+    merged.functions.push(...r.functions);
+    merged.docstrings.push(...r.docstrings);
+    for (const e of r.error_handling) {
+      errorCounts.set(e, (errorCounts.get(e) || 0) + 1);
+    }
+  }
+  merged.imports = Array.from(importCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([mod]) => mod);
+  merged.error_handling = Array.from(errorCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([p]) => p);
+  merged.types = merged.types.slice(0, 100);
+  merged.functions = merged.functions.slice(0, 100);
+  merged.docstrings = merged.docstrings.slice(0, 20);
+  return merged;
+}
+
+// src/parsers/cpp.ts
+var INCLUDE_RE = /#include\s*[<"]([^>"]+)[>"]/g;
+var TYPE_RE3 = /\b(?:class|struct|enum)\s+(\w+)/g;
+var FUNC_RE4 = /\b(?:void|int|float|double|char|bool|String|uint8_t|uint16_t|uint32_t)\s+(\w+)\s*\(/g;
+function parseCppFile(filepath, content) {
+  const result = {
+    imports: [],
+    types: [],
+    functions: [],
+    error_handling: []
+  };
+  let match;
+  while ((match = INCLUDE_RE.exec(content)) !== null) {
+    result.imports.push(match[1]);
+  }
+  while ((match = TYPE_RE3.exec(content)) !== null) {
+    result.types.push({
+      kind: "cpp",
+      name: match[1],
+      file: filepath
+    });
+  }
+  while ((match = FUNC_RE4.exec(content)) !== null) {
+    result.functions.push({
+      name: match[1],
+      file: filepath
+    });
+  }
+  if (/\btry\b|\bthrow\b|\bcatch\b/.test(content)) {
+    result.error_handling.push("try/throw/catch");
+  }
+  return result;
+}
+function mergeCppResults(results) {
+  const merged = {
+    imports: [],
+    types: [],
+    functions: [],
+    error_handling: []
+  };
+  const importCounts = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    for (const imp of r.imports) {
+      importCounts.set(imp, (importCounts.get(imp) || 0) + 1);
+    }
+    merged.types.push(...r.types);
+    merged.functions.push(...r.functions);
+    merged.error_handling.push(...r.error_handling);
+  }
+  merged.imports = Array.from(importCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([mod]) => mod);
+  merged.error_handling = [...new Set(merged.error_handling)];
+  return merged;
+}
+
+// src/extractors/keywordExtractor.ts
+var STDLIB_MODULES = /* @__PURE__ */ new Set([
+  // Python
+  "os",
+  "sys",
+  "typing",
+  "json",
+  "re",
+  "math",
+  "random",
+  "time",
+  "datetime",
+  "pathlib",
+  "dataclasses",
+  "enum",
+  "collections",
+  "itertools",
+  "functools",
+  "logging",
+  "argparse",
+  "subprocess",
+  "threading",
+  "multiprocessing",
+  "asyncio",
+  "socket",
+  "http",
+  "urllib",
+  "ssl",
+  "hashlib",
+  "base64",
+  "csv",
+  "sqlite3",
+  "pickle",
+  "tempfile",
+  "shutil",
+  "glob",
+  "io",
+  "string",
+  "struct",
+  "uuid",
+  "abc",
+  "copy",
+  "decimal",
+  "fractions",
+  "statistics",
+  "queue",
+  "signal",
+  "traceback",
+  "warnings",
+  "weakref",
+  "contextlib",
+  "unittest",
+  "pytest",
+  "tkinter",
+  "tk",
+  "ttk",
+  "types",
+  "inspect",
+  "platform",
+  // Common third-party generic plumbing
+  "requests",
+  "urllib3",
+  "pydantic",
+  "dotenv",
+  "yaml",
+  "tomllib"
+]);
+function platformFromPath(filePath) {
+  if (!filePath) return "app";
+  const fp = filePath.toLowerCase();
+  if (fp.endsWith(".ino") || fp.endsWith(".cpp") || fp.endsWith(".h") || fp.endsWith(".hpp") || fp.endsWith(".c")) {
+    if (fp.endsWith(".ino")) return "esp32";
+    if (fp.includes("firmware") || fp.includes("esp")) return "esp32";
+    return "app";
+  }
+  return "app";
+}
+function extractKeywords(sourceContext, basicAnalysis, repoDir, options) {
+  const keywords = [];
+  const effectiveStdlib = new Set(STDLIB_MODULES);
+  if ("imports" in sourceContext) {
+    for (const imp of sourceContext.imports) {
+      let module;
+      let count = 1;
+      let platform = "app";
+      if (typeof imp === "string") {
+        module = imp;
+      } else if (imp && typeof imp === "object" && "module" in imp) {
+        const impObj = imp;
+        module = impObj.module;
+        count = impObj.count || 1;
+        platform = platformFromPath(impObj.file || "");
+      } else {
+        continue;
+      }
+      if (effectiveStdlib.has(module.toLowerCase())) continue;
+      keywords.push({
+        keyword: module,
+        source: "import",
+        platform,
+        weight: 1 + (count - 1) * 0.1,
+        context: `Imported ${count} times`
+      });
+    }
+  }
+  if ("types" in sourceContext) {
+    for (const typeDecl of sourceContext.types) {
+      const name = typeDecl.name;
+      const kind = typeDecl.kind;
+      const platform = platformFromPath(typeDecl.file || "");
+      if (["View", "Model", "ViewModel", "Controller", "Service", "Manager"].includes(name)) continue;
+      keywords.push({
+        keyword: name,
+        source: "type_declaration",
+        platform,
+        weight: 1.5,
+        context: `${kind} declaration`
+      });
+    }
+  }
+  if ("functions" in sourceContext) {
+    for (const func of sourceContext.functions) {
+      const name = func.name;
+      const platform = platformFromPath(func.file || "");
+      if (["init", "setup", "configure", "initialize"].includes(name)) continue;
+      keywords.push({
+        keyword: name,
+        source: "function_signature",
+        platform,
+        weight: 1.2,
+        context: "Function signature"
+      });
+    }
+  }
+  if ("docstrings" in sourceContext && Array.isArray(sourceContext.docstrings)) {
+    for (const doc of sourceContext.docstrings) {
+      const firstSentence = doc.trim().split("\n")[0].slice(0, 120);
+      if (firstSentence.length > 15) {
+        keywords.push({
+          keyword: firstSentence,
+          source: "docstring",
+          platform: "app",
+          weight: 1.8,
+          context: "Docstring (domain intent)"
+        });
+      }
+    }
+  }
+  if ("frameworks_used" in sourceContext && Array.isArray(sourceContext.frameworks_used)) {
+    for (const fw of sourceContext.frameworks_used) {
+      const fwName = typeof fw === "string" ? fw : fw.framework || "";
+      if (fwName) {
+        keywords.push({
+          keyword: fwName,
+          source: "framework_usage",
+          platform: "app",
+          weight: 1.4,
+          context: "Framework usage (real practice)"
+        });
+      }
+    }
+  }
+  if ("property_wrappers" in sourceContext && Array.isArray(sourceContext.property_wrappers)) {
+    for (const wrapper of sourceContext.property_wrappers) {
+      const wrapperName = typeof wrapper === "string" ? wrapper : wrapper.wrapper || "";
+      if (wrapperName) {
+        keywords.push({
+          keyword: `@${wrapperName}`,
+          source: "property_wrapper",
+          platform: "app",
+          weight: 2,
+          context: "Property wrapper"
+        });
+      }
+    }
+  }
+  const errorPatterns = "error_handling" in sourceContext ? sourceContext.error_handling : "error_handling_patterns" in sourceContext ? sourceContext.error_handling_patterns || [] : [];
+  for (const error of errorPatterns) {
+    let pattern;
+    let platform = "app";
+    if (typeof error === "string") {
+      pattern = error;
+    } else if (error && typeof error === "object" && "pattern" in error) {
+      const errObj = error;
+      pattern = errObj.pattern;
+      platform = platformFromPath(errObj.file || "");
+    } else {
+      continue;
+    }
+    keywords.push({
+      keyword: pattern,
+      source: "error_handling",
+      platform,
+      weight: 1.3,
+      context: "Error handling pattern"
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueKeywords = [];
+  for (const kw of keywords) {
+    const key = kw.keyword.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      uniqueKeywords.push(kw);
+    }
+  }
+  return uniqueKeywords;
+}
+
+// src/utils/llmClient.ts
+var LlmClientError = class extends Error {
+  constructor(message, status, cause) {
+    super(message);
+    this.status = status;
+    this.cause = cause;
+    this.name = "LlmClientError";
+  }
+};
+function resolveProviderChain(config) {
+  const chain = [];
+  const push = (label, baseUrl, apiKey, model) => {
+    if (apiKey && baseUrl && model && !chain.some((c) => c.baseUrl === baseUrl && c.model === model)) {
+      chain.push({ label, baseUrl, apiKey, model });
+    }
+  };
+  if (config?.apiKey) {
+    push("config", config.baseUrl || "https://api.openai.com/v1", config.apiKey, config.model || "gpt-4o-mini");
+  }
+  push("legacy", process.env.LLM_BASE_URL || process.env.OPENAI_BASE_URL || "", process.env.LLM_API_KEY || process.env.OPENAI_API_KEY || "", process.env.LLM_MODEL || process.env.LLM_TIER_FAST || "");
+  push("dashscope", process.env.DASHSCOPE_BASE_URL || process.env.ALIBABA_BASE_URL || "", process.env.DASHSCOPE_API_KEY || process.env.ALIBABA_API_KEY || "", process.env.DASHSCOPE_MODEL || process.env.DEFAULT_AI_MODEL || "");
+  push("nvidia", "https://integrate.api.nvidia.com/v1", process.env.NVIDIA_API_KEY || "", process.env.NVIDIA_MODEL || "nvidia/nemotron-3-ultra-550b-a55b");
+  push("openrouter", "https://openrouter.ai/api/v1", process.env.OPENROUTER_API_KEY || "", process.env.OPENROUTER_MODEL || "nvidia/nemotron-3-ultra-550b-a55b");
+  if (process.env.OPENROUTER_MODEL) {
+    const or = chain.find((c) => c.label === "openrouter");
+    if (or) {
+      const rest = chain.filter((c) => c !== or);
+      return [or, ...rest];
+    }
+  }
+  return chain;
+}
+var MIN_REQUEST_INTERVAL_MS = 2500;
+var lastRequestAt = 0;
+async function pacedDelay() {
+  const wait = lastRequestAt + MIN_REQUEST_INTERVAL_MS - Date.now();
+  if (wait > 0) await new Promise((resolve2) => setTimeout(resolve2, wait));
+  lastRequestAt = Date.now();
+}
+function createLlmClient(config) {
+  const chain = resolveProviderChain(config);
+  const primary = chain[0];
+  if (!primary) {
+    throw new LlmClientError(
+      "No LLM provider configured. Set NVIDIA_API_KEY (primary) and/or OPENROUTER_API_KEY (fallback), or pass llmConfig."
+    );
+  }
+  primary.apiKey;
+  primary.baseUrl;
+  const model = primary.model;
+  async function chat(messages, options) {
+    const temperature = options?.temperature ?? config?.temperature ?? 0.1;
+    const maxTokens = options?.maxTokens ?? config?.maxTokens ?? parseInt(process.env.LLM_MAX_TOKENS || "65536", 10);
+    const attempts = [];
+    let lastError = null;
+    const TRANSIENT = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+    const REQUEST_TIMEOUT_MS = Number(process.env.LLM_REQUEST_TIMEOUT_MS || 3e5);
+    const MAX_CHAIN_ROUNDS = 3;
+    for (let round = 1; round <= MAX_CHAIN_ROUNDS; round++) {
+      if (round > 1) {
+        attempts.push("round " + (round - 1) + " failed \u2014 backing off 20s before rewalking the chain");
+        await new Promise((resolve2) => setTimeout(resolve2, 2e4));
+      }
+      for (const provider of chain) {
+        try {
+          const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${provider.apiKey}`
+          };
+          const payload = {
+            model: provider.model,
+            messages,
+            temperature,
+            max_tokens: maxTokens
+          };
+          await pacedDelay();
+          const doFetch = () => fetch(`${provider.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${provider.apiKey}`
+            },
+            body: JSON.stringify({
+              model: provider.model,
+              messages,
+              temperature,
+              max_tokens: maxTokens
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+          });
+          let response;
+          try {
+            response = await doFetch();
+          } catch (netErr) {
+            attempts.push(`${provider.label}: network error (${netErr instanceof Error ? netErr.message : String(netErr)}) \u2014 retrying once`);
+            await new Promise((r) => setTimeout(r, 5e3));
+            lastRequestAt = Date.now();
+            response = await doFetch();
+          }
+          if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            const err = new LlmClientError(
+              `[${provider.label}] LLM API error: ${response.status} ${response.statusText} \u2014 ${body.slice(0, 200)}`,
+              response.status
+            );
+            if (response.status === 429) {
+              const retryAfterRaw = response.headers.get("retry-after");
+              const retryAfterMs = Math.min(
+                6e4,
+                Math.max(15e3, (Number.isFinite(Number(retryAfterRaw)) ? Number(retryAfterRaw) : 20) * 1e3)
+              );
+              attempts.push(`${provider.label}: 429 rate-limited \u2014 backing off ${Math.round(retryAfterMs / 1e3)}s`);
+              await new Promise((resolve2) => setTimeout(resolve2, retryAfterMs));
+              lastRequestAt = Date.now();
+              const retry = await fetch(`${provider.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+              });
+              if (!retry.ok) throw err;
+              const retryData = await retry.json();
+              const retryContent2 = retryData.choices?.[0]?.message?.content || "";
+              if (!retryContent2.trim()) throw err;
+              return {
+                content: retryContent2,
+                model: retryData.model || provider.model,
+                provider: provider.label,
+                attempts: attempts.slice(),
+                usage: retryData.usage,
+                finishReason: retryData.choices?.[0]?.finish_reason
+              };
+            }
+            if (TRANSIENT.has(response.status)) {
+              await new Promise((r) => setTimeout(r, 3e3));
+              const retry = await fetch(`${provider.baseUrl}/chat/completions`, {
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                method: "POST",
+                headers: {
+                  "Content-Type": "application/json",
+                  "Authorization": `Bearer ${provider.apiKey}`
+                },
+                body: JSON.stringify({
+                  model: provider.model,
+                  messages,
+                  temperature,
+                  max_tokens: maxTokens
+                })
+              });
+              if (!retry.ok) throw err;
+              const retryData = await retry.json();
+              const retryContent = retryData.choices?.[0]?.message?.content || "";
+              return {
+                content: retryContent,
+                model: retryData.model || provider.model,
+                provider: provider.label,
+                attempts: attempts.slice(),
+                usage: retryData.usage,
+                finishReason: retryData.choices?.[0]?.finish_reason
+              };
+            }
+            throw err;
+          }
+          const data = await response.json();
+          const wrappedError = data.error;
+          if (wrappedError) {
+            throw new LlmClientError("[" + provider.label + "] upstream error " + (wrappedError.code ?? "") + ": " + (wrappedError.message ?? "unknown"));
+          }
+          const content = data.choices?.[0]?.message?.content || "";
+          if (!content.trim()) {
+            throw new LlmClientError("[" + provider.label + "] empty completion returned");
+          }
+          return {
+            content,
+            model: data.model || provider.model,
+            provider: provider.label,
+            attempts: attempts.slice(),
+            usage: data.usage,
+            finishReason: data.choices?.[0]?.finish_reason
+          };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          attempts.push(`${provider.label}: ${msg}`);
+          lastError = err instanceof LlmClientError ? err : new LlmClientError(`[${provider.label}] ${msg}`);
+        }
+      }
+      if (round < MAX_CHAIN_ROUNDS) continue;
+      throw lastError ?? new LlmClientError("All LLM providers failed (empty chain).");
+    }
+    throw lastError ?? new LlmClientError("All LLM providers failed after " + MAX_CHAIN_ROUNDS + " rounds.");
+  }
+  return { chat, model };
+}
+function parseJsonFromLlm(text) {
+  let cleaned = text.trim();
+  if (cleaned.startsWith("```json")) {
+    cleaned = cleaned.slice(7);
+  } else if (cleaned.startsWith("```")) {
+    cleaned = cleaned.slice(3);
+  }
+  if (cleaned.endsWith("```")) {
+    cleaned = cleaned.slice(0, -3);
+  }
+  cleaned = cleaned.trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    const start = cleaned.indexOf("{");
+    if (start >= 0) {
+      let depth = 0;
+      let inString = false;
+      let escape = false;
+      for (let i = start; i < cleaned.length; i++) {
+        const ch = cleaned[i];
+        if (escape) {
+          escape = false;
+          continue;
+        }
+        if (ch === "\\") {
+          escape = true;
+          continue;
+        }
+        if (ch === '"') {
+          inString = !inString;
+          continue;
+        }
+        if (inString) continue;
+        if (ch === "{") depth++;
+        if (ch === "}") {
+          depth--;
+          if (depth === 0) {
+            try {
+              return JSON.parse(cleaned.slice(start, i + 1));
+            } catch {
+            }
+          }
+        }
+      }
+    }
+    throw new LlmClientError(`Failed to parse JSON from LLM response: ${cleaned.slice(0, 200)}`);
+  }
+}
+async function llmChatJson(client, systemPrompt, userPrompt, options) {
+  const result = await client.chat(
+    [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: userPrompt }
+    ],
+    options
+  );
+  return parseJsonFromLlm(result.content);
+}
+
+// src/graph/scaffoldExtractor.ts
+async function extractScaffold(options) {
+  const { goal, techStack, fileList, llmConfig } = options;
+  const client = createLlmClient(llmConfig);
+  const fileListStr = fileList.length > 0 ? fileList.join("\n") : "(empty)";
+  const systemPrompt = "You are a programming pedagogy expert. For ONE concrete project, extract the 'FOUNDATION & SETUP' feature (id F0) \u2014 the COMPLETE set of 'MUST-KNOW' steps the learner needs before studying the first feature. Break it into concrete ACTION steps (5-8 steps), each with completion_level='base'. Include:\n1. Tools required for this tech stack (IDE, simulator/emulator, terminal, git, package manager) + basic operations (open project, build, run, debug, commit).\n2. Create the initial project: from a template OR clone/open the base-project (the provided repo).\n3. MINIMAL programming knowledge of the language (variables, types, functions, if/for, view declaration) + build one small demo (e.g. a single-screen Hello World app) BEFORE touching the real project.\n4. Repo map of the actual project: folder structure, entry point, how to build/run, main architecture (MVVM/Flux...), important packages/modules.\n5. Development loop (build->run->see result->debug), how to read/fix basic compile errors, minimal git workflow (clone/branch/commit/push).\nkeywords[]: real tool/language terms (e.g. 'Xcode', 'Simulator', 'Git', 'Swift', '@main', 'MVVM'). files[]: leave [] or use real paths if the step touches specific files. description: ONE concise sentence, MAX 140 characters. intent: WHY this step matters. outcome: {user_visible: string, technical: string}. acceptance[]: 2 verifiable criteria. effort: {estimated_minutes: number, complexity: low|medium|high}. NEVER invent. ALL text must be in ENGLISH (technical terms stay as-is). Return JSON containing only feature F0.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+
+PROJECT FILE LIST (base-project):
+${fileListStr}
+
+Return JSON:
+{
+  "feature": {
+    "id": "F0",
+    "name": "FOUNDATION & SETUP",
+    "description": "Get familiar with the tools, create/clone the project, learn minimal knowledge and the repo map",
+    "platform": "app",
+    "steps": [
+      {
+        "id": "F0-S1",
+        "sequence": 1,
+        "name": "Action step name",
+        "description": "Detailed description of the concrete actions",
+        "files": [],
+        "api_usage": [],
+        "keywords": ["Xcode", "Terminal"],
+        "completion_level": "base",
+        "intent": "Learn how to setup the IDE and run a minimal Swift app",
+        "outcome": {"user_visible": "App builds and runs", "technical": "Toolchain verified"},
+        "acceptance": ["Xcode builds without errors", "Simulator launches successfully"],
+        "effort": {"estimated_minutes": 20, "complexity": "low"}
+      }
+    ]
+  }
+}
+`;
+  try {
+    const result = await llmChatJson(client, systemPrompt, userPrompt, {
+      temperature: 0.1,
+      maxTokens: parseInt(process.env.PG_C0_MAX_TOKENS || "16384", 10)
+    });
+    const feat = result.feature;
+    if (!feat || !Array.isArray(feat.steps) || feat.steps.length === 0) {
+      console.warn("[WARN] Scaffold LLM returned no steps \u2014 skipping F0");
+      return null;
+    }
+    const steps = feat.steps.map((s, i) => ({
+      id: `F0-S${i + 1}`,
+      sequence: i + 1,
+      name: String(s.name || `Step ${i + 1}`),
+      description: String(s.description || ""),
+      files: Array.isArray(s.files) ? s.files : [],
+      api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+      keywords: Array.isArray(s.keywords) ? s.keywords : [],
+      completion_level: "base",
+      platform: String(s.platform || "app"),
+      intent: String(s.intent || ""),
+      outcome: s.outcome && typeof s.outcome === "object" ? s.outcome : void 0,
+      acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+      effort: s.effort && typeof s.effort === "object" ? s.effort : void 0,
+      requirement_ids: [],
+      concept_codes: []
+    }));
+    return {
+      id: "F0",
+      name: String(feat.name || "FOUNDATION & SETUP"),
+      description: String(feat.description || ""),
+      platform: String(feat.platform || "app"),
+      steps
+    };
+  } catch (err) {
+    console.error(`[ERROR] extractScaffold failed: ${err}`);
+    return null;
+  }
+}
+
+// src/graph/overviewExtractor.ts
+function buildSourceText(fileContentsMap) {
+  const blocks = [];
+  for (const [relPath, content] of fileContentsMap) {
+    blocks.push(`### FILE: ${relPath}
+${content}`);
+  }
+  return blocks.join("\n\n");
+}
+async function extractProjectOverview(options) {
+  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig } = options;
+  const client = createLlmClient(llmConfig);
+  const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
+  const allFilesStr = buildSourceText(fileContentsMap);
+  let keywordsAnchor = "";
+  if (astKeywords && astKeywords.length > 0) {
+    const kwItems = astKeywords.slice(0, 30).map(
+      (kw) => `- ${kw.keyword} (from ${kw.source})`
+    );
+    if (kwItems.length > 0) {
+      keywordsAnchor = "\nAST Domain Keywords & Patterns (from static analysis \u2014 use as context anchor):\n" + kwItems.join("\n") + "\n";
+    }
+  }
+  const systemPrompt = "You are a software architect. The app the user will build IS EXACTLY the provided files (not an SDK/lib). Analyze them and return a PROJECT OVERVIEW \u2014 meta only, DO NOT list steps (steps are handled in a later step). NEVER invent files/APIs. NEVER reference internal SDK/lib unless it appears in the given files.\nEND-USER VIEW (M1/Design Thinking): product.purpose must describe the USER PROBLEM (what the user does with the app, which need it solves). NEVER describe repo/artifacts.\nDEVELOPMENT STAGES: Include 4-6 development stages in product.development_stages. Each stage must have: stage (name), need (list of feature needs), learn (concepts learned), product_state (what works), temporary_approach, and validation.\nMISSING GAPS: Identify 0-5 missing_gaps (features/functionality that should exist but don't).\nTECH DEBT: Identify 0-5 tech_debt issues (code quality problems).\nALL text must be in ENGLISH.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+${keywordsAnchor}
+Filtered SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis, null, 0)}
+
+Source code of the files:
+${allFilesStr}
+
+Return JSON per the schema:
+{
+  "schema_version": 2,
+  "project": {"name": "...", "project_type": "app", "platforms": ["ios"]},
+  "product": {
+    "purpose": "END-USER problem being solved",
+    "problem_statement": "Core user problem",
+    "primary_users": ["who the main users are"],
+    "development_stages": [
+      {
+        "stage": "Stage 1: Foundation & Setup",
+        "need": ["Core app shell"],
+        "learn": ["App lifecycle, basic UI"],
+        "product_state": "App launches with static mock data",
+        "temporary_approach": "Hardcoded array",
+        "validation": "Main screen loads"
+      }
+    ],
+    "features": [
+      {"id": "F1", "name": "Feature name", "description": "Feature description", "platform": "ios"}
+    ],
+    "user_journeys": [{"name": "...", "feature_ids": ["F1"]}]
+  },
+  "architecture": {"layers": [], "services": [], "state_management": "..."},
+  "decomposition": {"milestones": [{"id": "M1", "phase": "MVP", "name": "...", "goal": "...", "feature_ids": ["F1"]}]}
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C1_MAX_TOKENS || "32768", 10)
+  });
+  const prod = result.product;
+  if (prod && !Array.isArray(prod.development_stages)) {
+    prod.development_stages = [];
+  }
+  return result;
+}
+
+// src/graph/stepExtractor.ts
+function buildSourceText2(fileContentsMap) {
+  const blocks = [];
+  for (const [relPath, content] of fileContentsMap) {
+    blocks.push(`### FILE: ${relPath}
+${content}`);
+  }
+  return blocks.join("\n\n");
+}
+async function extractFeatureSteps(options) {
+  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig } = options;
+  const client = createLlmClient(llmConfig);
+  const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
+  const allFilesStr = buildSourceText2(fileContentsMap);
+  const fid = feature.id || "F_UNK";
+  const fname = feature.name || fid;
+  const fdesc = feature.description || "";
+  const systemPrompt = "You are a software architect. Split ONE feature into ACTION steps (implementation steps) the learner must code sequentially. Each step must carry files[] (CORRECT paths in the source), api_usage[] (only from the provided SDK API index), keywords[] (real terms/language features in the files), and completion_level \u2208 {base, mvp, extend, polish}.\n  - base = foundation/setup\n  - mvp = make the app minimally WORKING for this feature\n  - extend = make it real/richer\n  - polish = robustness (error handling, tests, validation)\nInclude metadata: intent, outcome ({user_visible, technical}), acceptance[] (2 verifiable criteria), effort ({estimated_minutes, complexity}).\ndescription: ONE concise sentence, MAX 140 characters. NEVER invent files/APIs. Return ONLY the steps array. ALL text must be in ENGLISH.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+
+FEATURE TO SPLIT: ${fid} \u2014 ${fname}
+Feature description: ${fdesc}
+
+SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis)}
+
+Source code:
+${allFilesStr}
+
+Split this feature into 2-6 action steps. Return JSON:
+{
+  "steps": [
+    {
+      "id": "${fid}-S1",
+      "sequence": 1,
+      "name": "Action step name",
+      "description": "One concise sentence (max 140 chars)",
+      "files": ["path/to/file.swift"],
+      "api_usage": ["ChatClient"],
+      "keywords": ["@State", "NavigationStack"],
+      "completion_level": "mvp",
+      "intent": "Create reactive state container",
+      "outcome": {"user_visible": "Chat view updates", "technical": "ChatViewModel conforms to ObservableObject"},
+      "acceptance": ["ViewModel publishes messages", "UI re-renders on state mutation"],
+      "effort": {"estimated_minutes": 30, "complexity": "medium"}
+    }
+  ]
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C2_MAX_TOKENS || "32768", 10)
+  });
+  const rawSteps = result.steps || [];
+  const clampedSteps = rawSteps.length > 6 ? rawSteps.slice(0, 6) : rawSteps.length < 2 && rawSteps.length > 0 ? rawSteps : rawSteps;
+  if (rawSteps.length > 6) {
+    console.warn(`[WARN] LLM returned ${rawSteps.length} steps for ${fid}, clamped to 6`);
+  } else if (rawSteps.length === 0) {
+    console.warn(`[WARN] LLM returned 0 steps for ${fid}`);
+  }
+  return clampedSteps.map((s, i) => ({
+    id: `${fid}-S${i + 1}`,
+    sequence: i + 1,
+    name: String(s.name || `Step ${i + 1}`),
+    description: String(s.description || ""),
+    files: Array.isArray(s.files) ? s.files : [],
+    api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+    keywords: Array.isArray(s.keywords) ? s.keywords : [],
+    completion_level: String(s.completion_level || "mvp"),
+    platform: String(s.platform || feature.platform || "app"),
+    intent: String(s.intent || ""),
+    outcome: s.outcome,
+    acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+    effort: s.effort,
+    requirement_ids: [],
+    concept_codes: []
+  }));
+}
+async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig) {
+  const client = createLlmClient(llmConfig);
+  const usedSdkApis = sdkApiIndex.sdk_apis.filter((api) => api.used_in_demo).map((api) => api.name).slice(0, 2e3);
+  const sourceText = buildSourceText2(fileContentsMap);
+  const featuresListing = featuresMeta.map(
+    (f) => `- ${f.id || "F?"}: ${f.name || ""} \u2014 ${f.description || ""}`
+  ).join("\n");
+  const systemPrompt = "You are a software architect. Split MULTIPLE features into ACTION steps. Each step must carry files[], api_usage[], keywords[], and completion_level \u2208 {base, mvp, extend, polish}. Include metadata: intent, outcome ({user_visible, technical}), acceptance[] (2 verifiable criteria), effort ({estimated_minutes, complexity}). description: ONE concise sentence, MAX 140 characters. NEVER invent files/APIs. Return ONLY the JSON. ALL text must be in ENGLISH.";
+  const userPrompt = `App goal: ${goal}
+Tech stack: ${techStack}
+
+SDK API list (used_in_demo):
+${JSON.stringify(usedSdkApis)}
+
+Source code:
+${sourceText}
+
+FEATURES to split into steps:
+${featuresListing}
+
+For EACH feature above, produce 4-6 action steps. Each step must include:
+id, sequence, name, description, files, api_usage, keywords, completion_level, platform,
+intent, outcome ({user_visible, technical}), acceptance[] (2 criteria), effort ({estimated_minutes, complexity}).
+
+Return JSON with a "steps" dict keyed by feature_id:
+{
+  "steps": {
+    "<feature_id>": [
+      {
+        "id": "<feature_id>-S1",
+        "sequence": 1,
+        "name": "Step name",
+        "description": "Concise sentence (max 140 chars)",
+        "files": ["path/to/file"],
+        "api_usage": ["APIName"],
+        "keywords": ["keyword"],
+        "completion_level": "mvp",
+        "platform": "app",
+        "intent": "Step intent",
+        "outcome": {"user_visible": "User visible result", "technical": "Technical result"},
+        "acceptance": ["Criterion 1", "Criterion 2"],
+        "effort": {"estimated_minutes": 30, "complexity": "medium"}
+      }
+    ]
+  }
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.PG_C2_MAX_TOKENS || "32768", 10)
+  });
+  const stepsDict = result.steps;
+  const output = /* @__PURE__ */ new Map();
+  if (stepsDict && typeof stepsDict === "object") {
+    for (const [fid, rawSteps] of Object.entries(stepsDict)) {
+      if (!Array.isArray(rawSteps)) continue;
+      const featMeta = featuresMeta.find((f) => f.id === fid);
+      const steps = rawSteps.map((s, i) => ({
+        id: `${fid}-S${i + 1}`,
+        sequence: i + 1,
+        name: String(s.name || `Step ${i + 1}`),
+        description: String(s.description || ""),
+        files: Array.isArray(s.files) ? s.files : [],
+        api_usage: Array.isArray(s.api_usage) ? s.api_usage : [],
+        keywords: Array.isArray(s.keywords) ? s.keywords : [],
+        completion_level: String(s.completion_level || "mvp"),
+        platform: String(s.platform || featMeta?.platform || "app"),
+        intent: String(s.intent || ""),
+        outcome: s.outcome,
+        acceptance: Array.isArray(s.acceptance) ? s.acceptance : [],
+        effort: s.effort,
+        requirement_ids: [],
+        concept_codes: []
+      }));
+      output.set(fid, steps);
+    }
+  }
+  return output;
+}
+
+// src/graph/graphVerifier.ts
+function verifyProjectGraph(projectGraph, options) {
+  const { sdkApiIndex, fileContentsMap } = options;
+  const sdkApiNames = new Set(sdkApiIndex.sdk_apis.map((api) => api.name));
+  const hallucinations = [];
+  const features = projectGraph.features || [];
+  for (const feature of features) {
+    const fid = feature.id || "F_UNK";
+    const isFoundation = fid === "F0";
+    for (const step of feature.steps || []) {
+      const sid = step.id || `${fid}-SUNK`;
+      const validFiles = [];
+      for (const f of step.files || []) {
+        if (fileContentsMap.has(f)) {
+          validFiles.push(f);
+        } else {
+          hallucinations.push({
+            type: "file",
+            item: f,
+            feature_id: fid,
+            step_id: sid,
+            reason: `File '${f}' not found in repository`
+          });
+        }
+      }
+      step.files = validFiles;
+      const validApis = [];
+      for (const api of step.api_usage || []) {
+        if (sdkApiNames.size === 0 || sdkApiNames.has(api)) {
+          validApis.push(api);
+        } else {
+          hallucinations.push({
+            type: "api",
+            item: api,
+            feature_id: fid,
+            step_id: sid,
+            reason: `API '${api}' not found in SDK API index`
+          });
+        }
+      }
+      step.api_usage = validApis;
+      if (isFoundation) continue;
+      const validKws = [];
+      for (const kw of step.keywords || []) {
+        const kwLow = kw.toLowerCase();
+        const isSingleWord = !kwLow.includes(" ");
+        let found = false;
+        for (const f of validFiles) {
+          const content = (fileContentsMap.get(f) || "").toLowerCase();
+          if (isSingleWord) {
+            found = new RegExp(`\\b${kwLow.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(content);
+          } else {
+            found = content.includes(kwLow);
+          }
+          if (found) break;
+        }
+        if (!found) {
+          for (const content of fileContentsMap.values()) {
+            const lc = content.toLowerCase();
+            if (isSingleWord) {
+              found = new RegExp(`\\b${kwLow.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(lc);
+            } else {
+              found = lc.includes(kwLow);
+            }
+            if (found) break;
+          }
+        }
+        if (found) {
+          validKws.push(kw);
+        } else {
+          hallucinations.push({
+            type: "keyword",
+            item: kw,
+            feature_id: fid,
+            step_id: sid,
+            reason: `Keyword '${kw}' not found in target files`
+          });
+        }
+      }
+      step.keywords = validKws;
+    }
+  }
+  return { graph: projectGraph, hallucinations };
+}
+
+// src/graph/conceptEscalator.ts
+function toUpperSnake(term) {
+  let s = term.replace(/^[^\w]+/, "");
+  s = s.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+  s = s.replace(/[^\w]+/g, "_");
+  const res = s.toUpperCase().replace(/^_+|_+$/g, "");
+  return res || "CONCEPT";
+}
+function extractTermSnippets(term, fileContentsMap, maxSnippets = 1) {
+  const snippets = [];
+  const termLow = term.toLowerCase();
+  for (const [relPath, content] of fileContentsMap) {
+    const lines = content.split("\n");
+    for (let idx = 0; idx < lines.length; idx++) {
+      if (lines[idx].toLowerCase().includes(termLow)) {
+        const start = Math.max(0, idx - 1);
+        const end = Math.min(lines.length, idx + 2);
+        let snippet = lines.slice(start, end).map((l) => l.trim()).filter(Boolean).join(" ");
+        if (snippet.length > 120) snippet = snippet.slice(0, 120) + "...";
+        if (snippet) snippets.push(`[${relPath}]: ${snippet}`);
+        if (snippets.length >= maxSnippets) break;
+      }
+    }
+    if (snippets.length >= maxSnippets) break;
+  }
+  return snippets;
+}
+function inferDepthFromContext(keyword, fileContentsMap) {
+  const kw = keyword.toLowerCase();
+  const sioPatterns = [
+    /^@/,
+    // SwiftUI decorators: @State, @Binding
+    /^import\s/,
+    // Import statements
+    /\(\)$/,
+    // Function calls
+    /\.prototype/,
+    // Prototype methods
+    /^new\s/,
+    // Constructor calls
+    /^async\s/,
+    // Async keywords
+    /^await\s/
+  ];
+  if (sioPatterns.some((p) => p.test(keyword))) {
+    return { depth: "sio", rationale: `Keyword '${keyword}' is a specific API/syntax pattern` };
+  }
+  const cioPatterns = [
+    /pattern/i,
+    /protocol/i,
+    /architecture/i,
+    /lifecycle/i,
+    /observer/i,
+    /singleton/i,
+    /factory/i,
+    /delegate/i,
+    /state\s*management/i,
+    /data\s*flow/i,
+    /binding/i,
+    /mvvm/i,
+    /mvc/i,
+    /flux/i,
+    /redux/i,
+    /authentication/i,
+    /authorization/i,
+    /persistence/i,
+    /caching/i,
+    /serialization/i
+  ];
+  if (cioPatterns.some((p) => p.test(keyword))) {
+    return { depth: "cio", rationale: `Keyword '${keyword}' represents a mechanism/pattern` };
+  }
+  const uloPatterns = [
+    /design\s*thinking/i,
+    /user\s*needs/i,
+    /problem\s*statement/i,
+    /foundation/i,
+    /setup/i,
+    /overview/i,
+    /introduction/i,
+    /scaffold/i,
+    /hello\s*world/i,
+    /getting\s*started/i
+  ];
+  if (uloPatterns.some((p) => p.test(keyword))) {
+    return { depth: "ulo", rationale: `Keyword '${keyword}' is a foundational/introductory concept` };
+  }
+  for (const content of fileContentsMap.values()) {
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (line.toLowerCase().includes(kw)) {
+        if (/^(import|from|require|use |#include)/.test(line.trim())) {
+          return { depth: "sio", rationale: `Keyword '${keyword}' found in import statement` };
+        }
+        if (/^\/\/|^\/\*|^#|^-->/.test(line.trim())) {
+          return { depth: "ulo", rationale: `Keyword '${keyword}' found in comment/doc` };
+        }
+        return { depth: "sio", rationale: `Keyword '${keyword}' used in implementation code` };
+      }
+    }
+  }
+  return { depth: "sio", rationale: `Default: treating '${keyword}' as SIO (implementation-level)` };
+}
+async function escalateAndMapConcepts(options) {
+  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig } = options;
+  const features = projectGraph.features || [];
+  const allTerms = /* @__PURE__ */ new Set();
+  for (const feature of features) {
+    for (const step of feature.steps || []) {
+      for (const api of step.api_usage || []) allTerms.add(api);
+      for (const kw of step.keywords || []) allTerms.add(kw);
+    }
+  }
+  if (allTerms.size === 0) return /* @__PURE__ */ new Map();
+  const termList = Array.from(allTerms).sort();
+  let llmResults = {};
+  if (conceptMapOverride) {
+    llmResults = conceptMapOverride;
+  } else {
+    try {
+      const client = createLlmClient(llmConfig);
+      const conceptBank = (availableConcepts || []).sort().join(", ") || "(empty)";
+      const termEntries = termList.map((term) => {
+        const snippets = extractTermSnippets(term, fileContentsMap);
+        return snippets.length > 0 ? `- ${term} (Usage context: ${snippets[0]})` : `- ${term}`;
+      });
+      const systemPrompt = `You are a knowledge classification expert. For each concrete keyword/API, determine:
+1. The neutral concept it belongs to (UPPER_SNAKE_CASE)
+2. The depth level: ulo | cio | sio
+
+DEPTH DEFINITIONS:
+- ulo (WHAT + WHY): The keyword introduces a concept \u2014 "what is it, why does it exist"
+  Example: In a scaffold step, "@State is SwiftUI's way of managing local view state"
+- cio (HOW): The keyword demonstrates a mechanism \u2014 "how it works"
+  Example: "@State triggers view re-render when value changes \u2014 mechanism is value-type observation"
+- sio (IMPLEMENTATION): The keyword is a concrete API/syntax used in code
+  Example: "Using @State var isActive: Bool = false in ContentView"
+
+RULES:
+1. PREFER an EXISTING concept from the CONCEPT_BANK below if the keyword is a manifestation of that concept.
+2. ONLY create a NEW concept (UPPER_SNAKE_CASE, NOT ending in _CONCEPT, NOT containing a specific technology name) when NO concept in the bank covers it.
+3. CONCEPT_BANK: ${conceptBank.slice(0, 12e3)}
+4. Depth is per-keyword-in-context, NOT per-concept. The same concept can have ULO at one step and SIO at another.
+Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "...", "depth": "ulo|cio|sio"}}}`;
+      const userPrompt = "Classify the following keyword/API list into neutral concepts WITH depth levels.\nCode usage context is provided to disambiguate depth:\n" + termEntries.join("\n") + '\n\nReturn JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "...", "depth": "ulo|cio|sio"}}}';
+      const result = await llmChatJson(client, systemPrompt, userPrompt, {
+        temperature: 0.1,
+        maxTokens: 16384
+      });
+      llmResults = result.results || {};
+    } catch (err) {
+      console.warn(`[WARN] Concept escalation LLM failed (${err}), using fallback depth inference`);
+    }
+  }
+  const featureConcepts = /* @__PURE__ */ new Map();
+  for (const feature of features) {
+    const fid = feature.id || "F_UNK";
+    const featureFiles = /* @__PURE__ */ new Set();
+    for (const step of feature.steps || []) {
+      for (const f of step.files || []) featureFiles.add(f);
+    }
+    const fTerms = [
+      ...feature.api_usage || [],
+      ...(feature.steps || []).flatMap((s) => [...s.api_usage || [], ...s.keywords || []])
+    ];
+    const items = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const kw of fTerms) {
+      const info = llmResults[kw] || {};
+      const cCode = info.concept_code || toUpperSnake(kw);
+      const cName = info.concept_name || kw;
+      let depth = "sio";
+      let depthRationale = "Default: SIO";
+      if (info.depth && ["ulo", "cio", "sio"].includes(info.depth)) {
+        depth = info.depth;
+        depthRationale = `LLM classified as ${depth}`;
+      } else {
+        const inferred = inferDepthFromContext(kw, fileContentsMap);
+        depth = inferred.depth;
+        depthRationale = inferred.rationale;
+      }
+      const kwKey = `${cCode}::${kw}`;
+      if (seen.has(kwKey)) continue;
+      seen.add(kwKey);
+      const evidenceFiles = [];
+      for (const f of featureFiles) {
+        const content = fileContentsMap.get(f) || "";
+        if (content.toLowerCase().includes(kw.toLowerCase())) {
+          evidenceFiles.push(f);
+        }
+      }
+      items.push({
+        concept_code: cCode,
+        concept_name: cName,
+        keyword: kw,
+        depth,
+        depth_rationale: depthRationale,
+        evidence_files: evidenceFiles
+      });
+    }
+    featureConcepts.set(fid, items);
+  }
+  return featureConcepts;
+}
+
+// src/concepts/conceptResolver.ts
+var SOURCE_THRESHOLDS = {
+  docstring: 0.45,
+  readme_description: 0.45,
+  readme: 0.5,
+  type_declaration: 0.55,
+  function_signature: 0.55,
+  import: 0.6,
+  property_wrapper: 0.55,
+  error_handling: 0.6,
+  config: 0.6,
+  framework_usage: 0.45
+};
+var DEFAULT_THRESHOLD = 0.55;
+function uloCioAwareScore(query, depth, conceptData) {
+  const queryTerms = new Set(query.toLowerCase().split(/\s+/));
+  let targetText = "";
+  if (depth === "sio") {
+    targetText = conceptData.keywords || "";
+  } else if (depth === "cio") {
+    targetText = [conceptData.description || "", conceptData.cio || ""].join(" ");
+  } else {
+    targetText = [conceptData.ulo || "", conceptData.description || ""].join(" ");
+  }
+  const targetTerms = new Set(targetText.toLowerCase().split(/\s+/));
+  if (!queryTerms.size || !targetTerms.size) return 0;
+  let overlap = 0;
+  for (const t of queryTerms) {
+    if (targetTerms.has(t)) overlap++;
+  }
+  return Math.min(overlap / queryTerms.size, 1);
+}
+function inferFieldsFromGoal(goal) {
+  const goalLower = goal.toLowerCase();
+  const fieldKeywords = {
+    ASE: ["algorithm", "software", "programming", "code", "develop", "build", "app"],
+    DAI: ["data", "database", "storage", "query", "sql", "analytics"],
+    CSN: ["network", "protocol", "server", "client", "api", "http"],
+    HCI: ["user", "interface", "ui", "ux", "interaction", "design"],
+    MOB: ["mobile", "ios", "android", "swift", "kotlin", "flutter"],
+    WEB: ["web", "html", "css", "javascript", "react", "vue"]
+  };
+  const matched = [];
+  for (const [code, keywords] of Object.entries(fieldKeywords)) {
+    if (keywords.some((kw) => goalLower.includes(kw))) matched.push(code);
+  }
+  return matched.length > 0 ? matched : ["ASE"];
+}
+function inferDepthFromSource(source) {
+  const uloSources = ["docstring", "readme", "readme_description", "framework_usage"];
+  const cioSources = ["type_declaration", "function_signature", "config"];
+  if (uloSources.includes(source)) return "ulo";
+  if (cioSources.includes(source)) return "cio";
+  return "sio";
+}
+async function resolveConcepts(options) {
+  const { keywords, goal, embeddings, depthOverrides, topK = 3, threshold = DEFAULT_THRESHOLD} = options;
+  inferFieldsFromGoal(goal);
+  const resolved = [];
+  const proposed = [];
+  const hasEmbeddings = Object.keys(embeddings || {}).length > 0 && Object.values(embeddings || {}).some((d) => d.embedding && d.embedding.length > 0);
+  let search_mode = hasEmbeddings ? "embedding" : "keyword_overlap";
+  const concepts = embeddings || {};
+  for (const kwData of keywords) {
+    const keyword = kwData.keyword;
+    const source = kwData.source;
+    const depth = depthOverrides?.get(keyword) || inferDepthFromSource(source);
+    const scored = [];
+    for (const [code, data] of Object.entries(concepts)) {
+      const conceptKeywords = data.keywords || "";
+      const conceptDesc = data.description || "";
+      const conceptUlo = data.ulo;
+      const conceptCio = data.cio;
+      const awareScore = uloCioAwareScore(keyword, depth, {
+        keywords: conceptKeywords,
+        description: conceptDesc,
+        ulo: conceptUlo,
+        cio: conceptCio
+      });
+      const queryTerms = new Set(keyword.toLowerCase().split(/\s+/));
+      const allTerms = new Set([
+        ...conceptKeywords.toLowerCase().split(/\s+/),
+        ...conceptDesc.toLowerCase().split(/\s+/),
+        ...(conceptUlo || "").toLowerCase().split(/\s+/),
+        ...(conceptCio || "").toLowerCase().split(/\s+/)
+      ].filter(Boolean));
+      let overlapCount = 0;
+      for (const t of queryTerms) {
+        if (allTerms.has(t)) overlapCount++;
+      }
+      const fallbackScore = queryTerms.size > 0 ? Math.min(overlapCount / queryTerms.size, 1) : 0;
+      const usedAware = awareScore >= fallbackScore;
+      const finalScore = usedAware ? awareScore : fallbackScore;
+      if (finalScore > 0) {
+        scored.push({
+          code,
+          name: data.name || code,
+          description: conceptDesc,
+          keywords: conceptKeywords,
+          ulo: conceptUlo,
+          cio: conceptCio,
+          score: finalScore,
+          matched_level: usedAware ? depth : "sio",
+          method: hasEmbeddings && data.embedding && data.embedding.length > 0 ? "embedding" : "keyword_overlap"
+        });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const topMatches = scored.slice(0, topK);
+    if (topMatches.length === 0) {
+      proposed.push({
+        keyword,
+        source,
+        depth,
+        reason: "No matches in Master Tree"
+      });
+      continue;
+    }
+    const effThreshold = SOURCE_THRESHOLDS[source] || threshold;
+    const topMatch = topMatches[0];
+    if (topMatch.score >= effThreshold) {
+      resolved.push({
+        keyword,
+        source,
+        depth,
+        concept_codes: topMatches.filter((m) => m.score >= effThreshold).map((m) => m.code),
+        matches: topMatches
+      });
+    } else {
+      proposed.push({
+        keyword,
+        source,
+        depth,
+        best_match: topMatch,
+        reason: `Low confidence (${topMatch.score.toFixed(2)} < ${effThreshold})`
+      });
+    }
+  }
+  return {
+    resolved,
+    proposed,
+    summary: {
+      total_keywords: keywords.length,
+      resolved_count: resolved.length,
+      proposed_count: proposed.length,
+      search_mode
+    }
+  };
+}
+
+// src/assembly/roadmapAssembler.ts
+function calculateOverhead(rawMinutes, overheadFactor) {
+  return Math.ceil(rawMinutes * overheadFactor);
+}
+function splitFeatureIntoMilestones(feature, featureConcepts, maxMinutes, overheadFactor) {
+  const steps = feature.steps || [];
+  if (steps.length === 0) return [];
+  const featureId = feature.id || "F_UNK";
+  const stepMinutes = steps.map((s) => s.effort?.estimated_minutes || 15);
+  const totalRawMinutes = stepMinutes.reduce((a, b) => a + b, 0);
+  if (calculateOverhead(totalRawMinutes, overheadFactor) <= maxMinutes) {
+    return [buildMilestone(feature, featureConcepts, steps, stepMinutes, featureId, 1)];
+  }
+  const milestones = [];
+  let currentSteps = [];
+  let currentMinutes = [];
+  let milestoneIndex = 1;
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const mins = stepMinutes[i];
+    const currentTotal = currentMinutes.reduce((a, b) => a + b, 0);
+    if (calculateOverhead(currentTotal + mins, overheadFactor) > maxMinutes && currentSteps.length > 0) {
+      milestones.push(buildMilestone(
+        feature,
+        featureConcepts,
+        currentSteps,
+        currentMinutes,
+        featureId,
+        milestoneIndex
+      ));
+      milestoneIndex++;
+      currentSteps = [];
+      currentMinutes = [];
+    }
+    currentSteps.push(step);
+    currentMinutes.push(mins);
+  }
+  if (currentSteps.length > 0) {
+    milestones.push(buildMilestone(
+      feature,
+      featureConcepts,
+      currentSteps,
+      currentMinutes,
+      featureId,
+      milestoneIndex
+    ));
+  }
+  return milestones;
+}
+function buildMilestone(feature, featureConcepts, steps, stepMinutes, featureId, milestoneIndex) {
+  const rawMinutes = stepMinutes.reduce((a, b) => a + b, 0);
+  const levels = steps.map((s) => s.completion_level || "mvp");
+  const completionLevel = levels.includes("extend") ? "extend" : levels.includes("mvp") ? "mvp" : "base";
+  const milestoneConcepts = /* @__PURE__ */ new Set();
+  const milestoneKeywords = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    const stepConceptCodes = step.concept_codes || [];
+    for (const code of stepConceptCodes) {
+      milestoneConcepts.add(code);
+    }
+    const stepKws = [...step.keywords || [], ...step.api_usage || []];
+    for (const cm of featureConcepts) {
+      if (stepKws.includes(cm.keyword)) {
+        milestoneConcepts.add(cm.concept_code);
+        milestoneKeywords.add(cm.keyword);
+      }
+    }
+  }
+  const depthCounts = { ulo: 0, cio: 0, sio: 0 };
+  for (const cm of featureConcepts) {
+    if (milestoneKeywords.has(cm.keyword)) {
+      depthCounts[cm.depth]++;
+    }
+  }
+  const dominantDepth = depthCounts.sio >= depthCounts.cio && depthCounts.sio >= depthCounts.ulo ? "sio" : depthCounts.cio >= depthCounts.ulo ? "cio" : "ulo";
+  return {
+    id: milestoneIndex === 1 ? featureId : `${featureId}-M${milestoneIndex}`,
+    name: milestoneIndex === 1 ? feature.name || featureId : `${feature.name || featureId} (Part ${milestoneIndex})`,
+    description: feature.description || "",
+    feature_id: featureId,
+    feature_name: feature.name || "",
+    concept_code: [...milestoneConcepts].join(", "),
+    depth: dominantDepth,
+    all_keywords: [],
+    new_keywords: [],
+    prerequisite_keywords: [],
+    steps,
+    estimated_minutes: rawMinutes,
+    adjusted_minutes: rawMinutes,
+    // placeholder — assembleRoadmap() applies actual overheadFactor
+    completion_level: completionLevel
+  };
+}
+function buildKeywordMap(featureConcepts) {
+  const map = /* @__PURE__ */ new Map();
+  for (const mappings of featureConcepts.values()) {
+    for (const m of mappings) {
+      const existing = map.get(m.concept_code) || [];
+      if (!existing.includes(m.keyword)) {
+        existing.push(m.keyword);
+        map.set(m.concept_code, existing);
+      }
+    }
+  }
+  return map;
+}
+function attachKeywordsToMilestones(milestones, keywordMap) {
+  const cumulativeKeywords = /* @__PURE__ */ new Set();
+  for (const milestone of milestones) {
+    const allKw = /* @__PURE__ */ new Set();
+    const conceptCodes = milestone.concept_code.split(",").map((c) => c.trim()).filter(Boolean);
+    for (const code of conceptCodes) {
+      const kws = keywordMap.get(code) || [];
+      for (const kw of kws) allKw.add(kw);
+    }
+    milestone.all_keywords = Array.from(allKw).sort();
+    const newKw = [];
+    const prereqKw = [];
+    for (const kw of milestone.all_keywords) {
+      if (cumulativeKeywords.has(kw)) {
+        prereqKw.push(kw);
+      } else {
+        newKw.push(kw);
+        cumulativeKeywords.add(kw);
+      }
+    }
+    milestone.new_keywords = newKw;
+    milestone.prerequisite_keywords = prereqKw;
+  }
+  return milestones;
+}
+function groupIntoPhases(milestones, sessionMinutes) {
+  const phases = [];
+  let currentMilestones = [];
+  let currentMinutes = 0;
+  let phaseNum = 1;
+  for (const milestone of milestones) {
+    const milestoneMinutes = milestone.adjusted_minutes;
+    if (currentMinutes + milestoneMinutes > sessionMinutes && currentMilestones.length > 0) {
+      phases.push(buildPhase(currentMilestones, phaseNum));
+      phaseNum++;
+      currentMilestones = [];
+      currentMinutes = 0;
+    }
+    currentMilestones.push(milestone);
+    currentMinutes += milestoneMinutes;
+  }
+  if (currentMilestones.length > 0) {
+    phases.push(buildPhase(currentMilestones, phaseNum));
+  }
+  return phases;
+}
+function buildPhase(milestones, phaseNum) {
+  const totalMinutes = milestones.reduce((sum, m) => sum + m.adjusted_minutes, 0);
+  const depths = milestones.map((m) => m.depth);
+  const uniqueDepths = [...new Set(depths)];
+  const progression = uniqueDepths.map((d) => d.toUpperCase()).join(" \u2192 ");
+  return {
+    phase_id: phaseNum,
+    phase_name: `Phase ${phaseNum}`,
+    milestones,
+    total_minutes: totalMinutes,
+    concept_progression: progression
+  };
+}
+function assembleRoadmap(options) {
+  const {
+    projectGraph,
+    featureConcepts = /* @__PURE__ */ new Map(),
+    sessionMinutes = 90,
+    overheadFactor = 1.15,
+    maxMilestoneMinutes = 120
+  } = options;
+  const features = projectGraph.features || [];
+  const keywordMap = buildKeywordMap(featureConcepts);
+  const allMilestones = [];
+  for (const feature of features) {
+    const fid = feature.id || "F_UNK";
+    const fConcepts = featureConcepts.get(fid) || [];
+    const milestones = splitFeatureIntoMilestones(
+      feature,
+      fConcepts,
+      maxMilestoneMinutes,
+      overheadFactor
+    );
+    allMilestones.push(...milestones);
+  }
+  for (const milestone of allMilestones) {
+    milestone.adjusted_minutes = calculateOverhead(milestone.estimated_minutes, overheadFactor);
+  }
+  attachKeywordsToMilestones(allMilestones, keywordMap);
+  const phases = groupIntoPhases(allMilestones, sessionMinutes);
+  const totalEstimatedMinutes = allMilestones.reduce((sum, m) => sum + m.estimated_minutes, 0);
+  const totalAdjustedMinutes = allMilestones.reduce((sum, m) => sum + m.adjusted_minutes, 0);
+  return {
+    project: projectGraph.project,
+    product: projectGraph.product,
+    phases,
+    feature_concepts: featureConcepts,
+    time_budget: {
+      session_minutes: sessionMinutes,
+      overhead_factor: overheadFactor,
+      total_estimated_minutes: totalEstimatedMinutes,
+      total_adjusted_minutes: totalAdjustedMinutes
+    }
+  };
+}
+
+// src/extractors/fileSelector.ts
+async function selectFilesWithLlm(filePaths, goal, techStack, llmConfig) {
+  if (filePaths.length <= 15) {
+    return { selected: filePaths, reasoning: "Too few files to filter" };
+  }
+  const client = createLlmClient(llmConfig);
+  const treeLines = buildFileTree(filePaths);
+  const systemPrompt = 'You are a software architect analyzing a project repository.\nGiven a file tree and a project goal, select which files are MOST IMPORTANT to read for understanding the project architecture and implementation.\n\nRULES:\n1. Prioritize source code files (Swift, TS, Python, C++) over config/docs\n2. Include entry points (App.swift, main.py, index.ts)\n3. Include core domain files (models, services, views, controllers)\n4. EXCLUDE test files, mock files, generated files\n5. EXCLUDE config files (package.json, Podfile, etc.) unless they reveal architecture\n6. Include files that directly implement the features mentioned in the goal\n7. Return 20-40 files maximum (fewer is better if the project is small)\n\nReturn JSON: {"selected": ["path/to/file1", "path/to/file2"], "reasoning": "brief explanation"}';
+  const userPrompt = `Project goal: ${goal}
+Tech stack: ${techStack}
+
+FILE TREE (${filePaths.length} files):
+${treeLines}
+
+Select the most important files to analyze. Return JSON.`;
+  try {
+    const result = await llmChatJson(client, systemPrompt, userPrompt, {
+      temperature: 0.1,
+      maxTokens: 4096
+    });
+    const selected = Array.isArray(result.selected) ? result.selected : [];
+    const reasoning = String(result.reasoning || "");
+    const pathSet = new Set(filePaths);
+    const validSelected = selected.filter((p) => pathSet.has(p));
+    if (validSelected.length === 0) {
+      return { selected: filePaths, reasoning: "LLM selection empty, using all files" };
+    }
+    return { selected: validSelected, reasoning };
+  } catch (err) {
+    console.warn(`[WARN] LLM file selection failed (${err}), using all files`);
+    return { selected: filePaths, reasoning: `LLM failed: ${err}` };
+  }
+}
+function buildFileTree(filePaths) {
+  const byDir = /* @__PURE__ */ new Map();
+  for (const fp of filePaths) {
+    const parts = fp.split("/");
+    const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : "(root)";
+    const file = parts[parts.length - 1];
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(file);
+  }
+  const lines = [];
+  for (const [dir, files] of byDir) {
+    lines.push(`${dir}/`);
+    for (const f of files.sort()) {
+      lines.push(`  ${f}`);
+    }
+  }
+  return lines.join("\n");
+}
+function collectSourceFiles(dir, options) {
+  const allowedExts = [".swift", ".ts", ".tsx", ".js", ".jsx", ".py", ".ino", ".cpp", ".c", ".h", ".hpp"];
+  const maxFiles = 70;
+  const gitFiles = collectViaGit(dir, allowedExts, maxFiles);
+  if (gitFiles.length > 0) return gitFiles;
+  return collectViaFilesystem(dir, allowedExts, maxFiles);
+}
+function collectViaGit(dir, allowedExts, maxFiles) {
+  try {
+    const raw = child_process.execSync("git ls-files --cached --others --exclude-standard", {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 5e3,
+      maxBuffer: 1024 * 1024
+    });
+    const extSet = new Set(allowedExts.map((e) => e.toLowerCase()));
+    return raw.split("\n").filter((line) => line.length > 0).filter((line) => extSet.has(path.extname(line).toLowerCase())).slice(0, maxFiles).map((rel) => path.join(dir, rel));
+  } catch {
+    return [];
+  }
+}
+function collectViaFilesystem(dir, allowedExts, maxFiles, skipDirs) {
+  const skipSet = new Set([
+    "node_modules",
+    ".build",
+    "Pods",
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    ".idea",
+    ".vscode",
+    "test",
+    "tests",
+    "demo",
+    "sample",
+    "example",
+    "playground"
+  ]);
+  const extSet = new Set(allowedExts.map((e) => e.toLowerCase()));
+  const result = [];
+  function walk(currentDir) {
+    if (result.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (result.length >= maxFiles) return;
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!skipSet.has(entry.name)) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (extSet.has(ext)) {
+          result.push(fullPath);
+        }
+      }
+    }
+  }
+  walk(dir);
+  return result;
+}
+function collectSpecificFileContents(dir, relativePaths, maxChars = 5e5) {
+  const contents = /* @__PURE__ */ new Map();
+  let totalChars = 0;
+  for (const relPath of relativePaths) {
+    const fullPath = path.join(dir, relPath);
+    try {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      if (totalChars + content.length > maxChars) {
+        const remaining = maxChars - totalChars;
+        if (remaining > 100) {
+          contents.set(relPath, content.slice(0, remaining));
+          totalChars += remaining;
+        }
+        break;
+      }
+      contents.set(relPath, content);
+      totalChars += content.length;
+    } catch {
+    }
+  }
+  return contents;
+}
+function detectPrimaryLanguage(filePaths) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const fp of filePaths) {
+    const ext = path.extname(fp).toLowerCase();
+    let lang = "unknown";
+    if (ext === ".swift") lang = "Swift";
+    else if (ext === ".ts" || ext === ".tsx") lang = "TypeScript";
+    else if (ext === ".js" || ext === ".jsx") lang = "JavaScript";
+    else if (ext === ".py") lang = "Python";
+    else if (ext === ".ino" || ext === ".cpp" || ext === ".c" || ext === ".h") lang = "C++";
+    else if (ext === ".kt" || ext === ".kts") lang = "Kotlin";
+    counts.set(lang, (counts.get(lang) || 0) + 1);
+  }
+  let maxCount = 0;
+  let primary = "unknown";
+  for (const [lang, count] of counts) {
+    if (count > maxCount) {
+      maxCount = count;
+      primary = lang;
+    }
+  }
+  return primary;
+}
+async function runProjectGraphPipeline(options) {
+  const { repoDir, goal, techStack, llmConfig, embeddings, onProgress } = options;
+  const log = (step, msg) => {
+    console.log(`[${step}] ${msg}`);
+    onProgress?.(step, msg);
+  };
+  log("STEP_1", "Scanning file tree (names only)...");
+  const allFilePaths = collectSourceFiles(repoDir);
+  const allRelPaths = allFilePaths.map((fp) => path.relative(repoDir, fp));
+  log("STEP_1", `Found ${allRelPaths.length} source files in repository`);
+  log("STEP_1", "Asking LLM to select relevant files from file tree...");
+  const { selected: selectedPaths, reasoning } = await selectFilesWithLlm(
+    allRelPaths,
+    goal,
+    techStack,
+    llmConfig
+  );
+  log("STEP_1", `LLM selected ${selectedPaths.length}/${allRelPaths.length} files: ${reasoning.slice(0, 100)}`);
+  log("STEP_1", "Reading content for selected files...");
+  const fileContentsMap = collectSpecificFileContents(repoDir, selectedPaths);
+  const filePaths = selectedPaths;
+  const primaryLang = detectPrimaryLanguage(filePaths);
+  log("STEP_1", `Primary language: ${primaryLang}, ${filePaths.length} files loaded (${fileContentsMap.size} with content)`);
+  log("STEP_1", "Parsing source files with AST-level analysis...");
+  const allParseResults = [];
+  for (const [relPath, content] of fileContentsMap) {
+    const fullPath = relPath;
+    if (fullPath.endsWith(".swift")) {
+      allParseResults.push(parseSwiftFile(fullPath, content));
+    } else if (fullPath.endsWith(".ts") || fullPath.endsWith(".tsx") || fullPath.endsWith(".js") || fullPath.endsWith(".jsx")) {
+      allParseResults.push(parseTsFile(fullPath, content));
+    } else if (fullPath.endsWith(".py")) {
+      allParseResults.push(parsePythonFile(fullPath, content));
+    } else if (fullPath.endsWith(".ino") || fullPath.endsWith(".cpp") || fullPath.endsWith(".c") || fullPath.endsWith(".h")) {
+      allParseResults.push(parseCppFile(fullPath, content));
+    }
+  }
+  let mergedContext;
+  if (primaryLang === "Swift") {
+    mergedContext = mergeSwiftResults(allParseResults.filter((r) => "property_wrappers" in r));
+  } else if (primaryLang === "TypeScript" || primaryLang === "JavaScript") {
+    mergedContext = mergeTsResults(allParseResults.filter((r) => !("docstrings" in r) && !("property_wrappers" in r) && !("frameworks_used" in r)));
+  } else if (primaryLang === "Python") {
+    mergedContext = mergePythonResults(allParseResults.filter((r) => "docstrings" in r));
+  } else {
+    mergedContext = mergeCppResults(allParseResults.filter((r) => "error_handling" in r && !("docstrings" in r) && !("property_wrappers" in r)));
+  }
+  log("STEP_2", "Extracting keywords from AST analysis...");
+  const astKeywords = extractKeywords(mergedContext);
+  log("STEP_2", `Extracted ${astKeywords.length} keywords`);
+  log("STEP_3", "Building SDK API index...");
+  const sdkApiIndex = {
+    sdk_apis: astKeywords.map((kw) => ({
+      name: kw.keyword,
+      kind: kw.source,
+      used_in_demo: true
+    }))
+  };
+  log("STEP_4", "Generating project graph via LLM (C0: Scaffold, C1: Overview, C2: Steps)...");
+  log("STEP_4_C0", "Extracting FOUNDATION & SETUP feature (F0)...");
+  const scaffoldFeature = await extractScaffold({
+    goal,
+    techStack,
+    fileList: filePaths,
+    llmConfig
+  });
+  log("STEP_4_C1", "Extracting project overview (features meta)...");
+  const overview = await extractProjectOverview({
+    goal,
+    techStack,
+    sdkApiIndex,
+    fileContentsMap,
+    astKeywords,
+    llmConfig
+  });
+  const product = overview.product;
+  const pblStep = {
+    id: "F0-S1",
+    sequence: 1,
+    name: "Frame the problem & understand user needs (Design Thinking)",
+    description: "BEFORE CODING \u2014 frame the problem and understand what the user needs",
+    files: [],
+    api_usage: [],
+    keywords: ["Design Thinking", "User Needs", "Problem Statement", "User Journey", "PBL"],
+    completion_level: "base",
+    platform: "app",
+    intent: "Understand user needs and frame problem before writing code",
+    outcome: { user_visible: "Defined problem statement", technical: "Problem frame context" },
+    acceptance: ["Problem statement is clear", "Primary users identified"],
+    requirement_ids: [],
+    concept_codes: [],
+    effort: { estimated_minutes: 15, complexity: "low" }
+  };
+  let featuresFull = [];
+  if (scaffoldFeature) {
+    const scaffoldSteps = [pblStep, ...scaffoldFeature.steps || []].map((s, i) => ({
+      ...s,
+      id: `F0-S${i + 1}`,
+      sequence: i + 1
+    }));
+    featuresFull.push({
+      ...scaffoldFeature,
+      id: "F0",
+      name: "FOUNDATION & SETUP",
+      steps: scaffoldSteps
+    });
+  } else {
+    featuresFull.push({
+      id: "F0",
+      name: "FOUNDATION & SETUP",
+      description: "Frame the problem, get familiar with the tools",
+      steps: [pblStep]
+    });
+  }
+  const overviewFeatures = product?.features || [];
+  featuresFull = [...featuresFull, ...overviewFeatures];
+  log("STEP_4_C2", `Extracting steps for ${overviewFeatures.length} features...`);
+  const nonF0Features = overviewFeatures.filter((f) => f.id !== "F0");
+  if (nonF0Features.length > 0) {
+    try {
+      const batchedSteps = await extractFeatureStepsBatched(
+        goal,
+        techStack,
+        sdkApiIndex,
+        fileContentsMap,
+        nonF0Features,
+        llmConfig
+      );
+      for (const feature of nonF0Features) {
+        const steps = batchedSteps.get(feature.id || "");
+        if (steps) feature.steps = steps;
+      }
+    } catch (err) {
+      log("STEP_4_C2", `Batch extraction failed (${err}), falling back to per-feature...`);
+      for (const feature of nonF0Features) {
+        try {
+          const steps = await extractFeatureSteps({
+            goal,
+            techStack,
+            sdkApiIndex,
+            fileContentsMap,
+            feature,
+            llmConfig
+          });
+          feature.steps = steps;
+        } catch (e) {
+          log("STEP_4_C2", `Failed for ${feature.id}: ${e}`);
+        }
+      }
+    }
+  }
+  const projectGraph = {
+    schema_version: 3,
+    project: {
+      id: overview.project?.name?.toString().toLowerCase().replace(/\s+/g, "-") || "project",
+      name: overview.project?.name?.toString() || "Project",
+      purpose: goal,
+      version: "0.1.0",
+      project_type: "app",
+      platform: overview.project?.platforms || ["ios"],
+      tech_stack: techStack.split(",").reduce((acc, t) => {
+        const key = t.trim().toLowerCase();
+        if (key) acc[key] = [t.trim()];
+        return acc;
+      }, {}),
+      architecture: overview.architecture?.layers || []
+    },
+    product: {
+      goals: product?.goals || [],
+      users: product?.users || [],
+      journeys: product?.user_journeys || [],
+      requirements: [],
+      development_stages: product?.development_stages || [],
+      purpose: String(product?.purpose || ""),
+      problem_statement: String(product?.problem_statement || ""),
+      primary_users: product?.primary_users || []
+    },
+    features: featuresFull,
+    capabilities: [],
+    implementation: {
+      tasks: []
+    },
+    missing_gaps: [],
+    tech_debt: []
+  };
+  log("STEP_5", "Verifying project graph against source code...");
+  const { graph: verifiedGraph, hallucinations } = verifyProjectGraph(projectGraph, {
+    sdkApiIndex,
+    fileContentsMap
+  });
+  log("STEP_5", `Verification complete: ${hallucinations.length} hallucinations found`);
+  log("STEP_6", "Escalating keywords to neutral concepts...");
+  const featureConcepts = await escalateAndMapConcepts({
+    projectGraph: verifiedGraph,
+    fileContentsMap,
+    llmConfig
+  });
+  log("STEP_6", `Concept mapping complete: ${featureConcepts.size} features mapped`);
+  for (const feature of verifiedGraph.features || []) {
+    const fid = feature.id || "";
+    const fConcepts = featureConcepts.get(fid) || [];
+    for (const step of feature.steps || []) {
+      const stepConcepts = fConcepts.filter((cm) => {
+        const stepKws = [...step.keywords || [], ...step.api_usage || []];
+        return stepKws.some((k) => k === cm.keyword);
+      }).map((cm) => cm.concept_code);
+      const existing = step.concept_codes || [];
+      step.concept_codes = [.../* @__PURE__ */ new Set([...existing, ...stepConcepts])];
+    }
+  }
+  log("STEP_7", "Resolving keywords to Master Tree concepts...");
+  const llmKeywords = [];
+  const seenKw = /* @__PURE__ */ new Set();
+  for (const feature of verifiedGraph.features || []) {
+    for (const step of feature.steps || []) {
+      for (const kw of [...step.keywords || [], ...step.api_usage || []]) {
+        if (!seenKw.has(kw.toLowerCase())) {
+          seenKw.add(kw.toLowerCase());
+          llmKeywords.push({ keyword: kw, source: "llm_step", platform: "app", weight: 1, context: "LLM-generated step keyword" });
+        }
+      }
+    }
+  }
+  const astKwMap = new Map(astKeywords.map((k) => [k.keyword.toLowerCase(), k]));
+  const mergedKeywords = [];
+  const mergedSeen = /* @__PURE__ */ new Set();
+  for (const kw of [...astKeywords, ...llmKeywords]) {
+    const key = kw.keyword.toLowerCase();
+    if (!mergedSeen.has(key)) {
+      mergedSeen.add(key);
+      mergedKeywords.push(astKwMap.get(key) || kw);
+    }
+  }
+  const depthOverrides = /* @__PURE__ */ new Map();
+  for (const mappings of featureConcepts.values()) {
+    for (const cm of mappings) {
+      if (!depthOverrides.has(cm.keyword)) {
+        depthOverrides.set(cm.keyword, cm.depth);
+      }
+    }
+  }
+  const resolvedConcepts = await resolveConcepts({
+    keywords: mergedKeywords,
+    goal,
+    embeddings,
+    depthOverrides});
+  log("STEP_7", `Resolved: ${resolvedConcepts.summary.resolved_count}, Proposed: ${resolvedConcepts.summary.proposed_count} (${resolvedConcepts.summary.search_mode})`);
+  log("STEP_8", "Assembling roadmap with keyword tracking...");
+  const roadmap = assembleRoadmap({
+    projectGraph: verifiedGraph,
+    featureConcepts,
+    sessionMinutes: 90,
+    overheadFactor: 1.15,
+    maxMilestoneMinutes: 120
+  });
+  log("STEP_8", `Roadmap assembled: ${roadmap.phases.length} phases, ${roadmap.phases.reduce((s, p) => s + p.milestones.length, 0)} milestones`);
+  return {
+    projectGraph: verifiedGraph,
+    resolvedConcepts,
+    roadmap,
+    hallucinations,
+    keywords: astKeywords,
+    featureConcepts
+  };
+}
+
+exports.runProjectGraphPipeline = runProjectGraphPipeline;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map