@thanh01.pmt/domain-kit 0.1.0 → 0.2.1

package/dist/{chunk-3VVPSRAM.mjs → chunk-CRN6D4HG.mjs}

@@ -1,8 +1,856 @@
-import { createLlmClient, llmChatJson, parseJsonFromLlm } from './chunk-MOKNFLUD.mjs';
+import { parseSyllabus } from './chunk-T4Y2DE2W.mjs';
 import { readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
+// 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:free");
+  push("openrouter", "https://openrouter.ai/api/v1", process.env.OPENROUTER_API_KEY || "", process.env.OPENROUTER_MODEL || "nvidia/nemotron-3-ultra-550b-a55b:free");
+  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((resolve) => setTimeout(resolve, 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((resolve) => setTimeout(resolve, 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((resolve) => setTimeout(resolve, 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/graph/loCodeStandard.ts
 var TECH_TAG_MAP = {
   python: "PY",
@@ -119,30 +967,160 @@ var ULO_CODE_RE = /^ULO-[A-Z][A-Z0-9_]*-\d{2}$/;
 var CIO_CODE_RE = /^CIO-[A-Z][A-Z0-9_]*-\d{2}-[A-Z][A-Z0-9_]*$/;
 var SIO_CODE_RE = /^SIO-[A-Z0-9]+-[A-Z][A-Z0-9_]*-\d{2}$/;
 
-// src/graph/loExemplars.ts
-var ULO_EXEMPLARS = [
-  // Calibrated against production learning_objectives (UNIVERSAL rows, neutral)
-  "The learner will be able to recall the key concepts, terminology, and characteristics of layers of abstraction.",
-  "The learner will be able to explain how layers of abstraction hide implementation details while exposing essential behavior.",
-  "The learner will be able to explain how a program changes state through statements and control flow.",
-  "The learner will be able to differentiate local from global scope and describe how return values affect data flow.",
-  "The learner will be able to describe the mechanism of a loop, including its condition, step and stopping rule.",
-  "The learner will be able to explain why a representation format must balance readability against processing efficiency."
-];
-var CIO_EXEMPLARS = [
-  // Production CONCEPTUAL_IMPL rows: mechanism behind the clause, Marr 2-Language neutral
-  "The learner will be able to develop a conceptual model that explains the internal mechanism by which the representation produces its effect.",
-  "The learner will be able to compare alternative approaches for the same operation and describe the trade-offs between them.",
-  "The learner will be able to decompose the choice of representation into decisive criteria such as cost, fidelity and tolerance to change.",
-  "The learner will be able to describe the sequence of steps by which a process transforms its input into its output, including the stopping condition."
-];
-var SIO_EXEMPLARS = [
-  // Production SPECIFIC_IMPL style: keyword-bound completable tasks, tech-tagged tier
-  "The learner will be able to use argparse.ArgumentParser with add_subparsers to register add, done and list commands in a Python CLI.",
-  "The learner will be able to define a @dataclass with type hints and a __post_init__ method that raises ValueError on invariant violation.",
-  "The learner will be able to execute parameterized statements via sqlite3.Connection.execute inside a with conn: transaction to perform CRUD on a tasks table.",
-  "The learner will be able to write a pytest test that runs the CLI entry point via subprocess.run and asserts the exit code and printed output."
-];
+// src/graph/knowledgeGraphVerifier.ts
+function detectPrerequisiteCycles(concepts) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  const path = [];
+  const prereqMap = /* @__PURE__ */ new Map();
+  for (const c of concepts) {
+    prereqMap.set(c.id, c.prerequisites || []);
+  }
+  function dfs(conceptId) {
+    if (inStack.has(conceptId)) {
+      const cycleStart = path.indexOf(conceptId);
+      if (cycleStart >= 0) {
+        cycles.push([...path.slice(cycleStart), conceptId]);
+      }
+      return;
+    }
+    if (visited.has(conceptId)) return;
+    visited.add(conceptId);
+    inStack.add(conceptId);
+    path.push(conceptId);
+    for (const prereq of prereqMap.get(conceptId) || []) {
+      dfs(prereq);
+    }
+    path.pop();
+    inStack.delete(conceptId);
+  }
+  for (const c of concepts) {
+    if (!visited.has(c.id)) {
+      dfs(c.id);
+    }
+  }
+  return cycles;
+}
+function breakPrerequisiteCycles(concepts, cycles) {
+  const removed = [];
+  const fixed = concepts.map((c) => ({ ...c, prerequisites: [...c.prerequisites || []] }));
+  for (const cycle of cycles) {
+    if (cycle.length >= 2) {
+      const breaker = cycle[cycle.length - 2];
+      const target = cycle[cycle.length - 1];
+      for (const concept of fixed) {
+        if (concept.id === breaker && target) {
+          concept.prerequisites = concept.prerequisites.filter((p) => p !== target);
+          removed.push({ from: breaker, to: target });
+        }
+      }
+    }
+  }
+  return { fixed, removed };
+}
+function auditSyllabusCoverage(concepts, syllabus) {
+  if (!syllabus || syllabus.allTopics.length === 0) {
+    return { coverageRatio: 1, totalTopics: 0, coveredTopics: 0, uncovered: [] };
+  }
+  const topics = syllabus.allTopics;
+  const coveredSet = /* @__PURE__ */ new Set();
+  for (const topic of topics) {
+    const topicKeywords = /* @__PURE__ */ new Set([
+      ...topic.title.toLowerCase().split(/\s+/),
+      ...(topic.keywords || []).map((k) => k.toLowerCase())
+    ]);
+    for (const concept of concepts) {
+      concept.name.toLowerCase();
+      (concept.description || "").toLowerCase();
+      (concept.keywords || []).map((k) => k.toLowerCase());
+      if (concept.id.toLowerCase() === topic.id.toLowerCase()) {
+        coveredSet.add(topic.id);
+        break;
+      }
+      const refs = concept.references || [];
+      const hasTopicRef = refs.some(
+        (r) => r.id === topic.id || r.title && r.title.toLowerCase() === topic.title.toLowerCase()
+      );
+      if (hasTopicRef) {
+        coveredSet.add(topic.id);
+        break;
+      }
+      const conceptKeywords = (concept.keywords || []).map((k) => k.toLowerCase());
+      const hasOverlap = conceptKeywords.some((k) => topicKeywords.has(k)) || concept.name.toLowerCase().includes(topic.title.toLowerCase()) || topic.title.toLowerCase().includes(concept.name.toLowerCase());
+      if (hasOverlap) {
+        coveredSet.add(topic.id);
+        break;
+      }
+    }
+  }
+  const totalTopics = topics.length;
+  const coveredTopics = coveredSet.size;
+  const coverageRatio = totalTopics > 0 ? coveredTopics / totalTopics : 1;
+  const uncovered = topics.filter((t) => !coveredSet.has(t.id)).map((t) => `${t.id}: ${t.title}`);
+  return { coverageRatio, totalTopics, coveredTopics, uncovered };
+}
+function verifyKnowledgeGraph(kg, syllabusOrOptions) {
+  const syllabus = syllabusOrOptions && "parsedSyllabus" in syllabusOrOptions ? syllabusOrOptions.parsedSyllabus : syllabusOrOptions;
+  const warnings = [];
+  let concepts = [...kg.concepts || []];
+  const conceptIds = new Set(concepts.map((c) => c.id));
+  for (const c of concepts) {
+    if ((c.prerequisites || []).includes(c.id)) {
+      c.prerequisites = (c.prerequisites || []).filter((p) => p !== c.id);
+      warnings.push(`Self-loop removed on concept ${c.id}`);
+    }
+  }
+  const danglingPrerequisites = [];
+  for (const c of concepts) {
+    const validPrereqs = [];
+    for (const p of c.prerequisites || []) {
+      if (!conceptIds.has(p)) {
+        danglingPrerequisites.push({ conceptId: c.id, missingPrereqId: p });
+        warnings.push(`Dangling prerequisite removed: ${c.id} -> ${p}`);
+      } else {
+        validPrereqs.push(p);
+      }
+    }
+    c.prerequisites = validPrereqs;
+  }
+  const initialCycles = detectPrerequisiteCycles(concepts);
+  let removedEdges = [];
+  if (initialCycles.length > 0) {
+    const broken = breakPrerequisiteCycles(concepts, initialCycles);
+    concepts = broken.fixed;
+    removedEdges = broken.removed;
+    for (const r of removedEdges) {
+      warnings.push(`Cycle broken: removed edge ${r.from} -> ${r.to}`);
+    }
+  }
+  const coverage = auditSyllabusCoverage(concepts, syllabus);
+  if (coverage.coverageRatio < 1) {
+    warnings.push(`Syllabus coverage ${(coverage.coverageRatio * 100).toFixed(1)}% (${coverage.coveredTopics}/${coverage.totalTopics} topics). Uncovered: ${coverage.uncovered.join(", ")}`);
+  }
+  for (const c of concepts) {
+    if (!c.ulo) warnings.push(`Concept ${c.id} missing ULO (WHAT + WHY)`);
+    if (!c.cio) warnings.push(`Concept ${c.id} missing CIO (HOW mechanism)`);
+    if (!c.sio || c.sio.length === 0) warnings.push(`Concept ${c.id} missing SIO implementation items`);
+  }
+  const valid = initialCycles.length === 0 && danglingPrerequisites.length === 0 && coverage.coverageRatio >= 0.8;
+  const verifiedGraph = {
+    ...kg,
+    concepts
+  };
+  const report = {
+    valid,
+    cycles: initialCycles,
+    removedEdges,
+    danglingPrerequisites,
+    coverageRatio: coverage.coverageRatio,
+    totalSyllabusTopics: coverage.totalTopics,
+    coveredSyllabusTopics: coverage.coveredTopics,
+    uncoveredTopics: coverage.uncovered,
+    warnings
+  };
+  return { verifiedGraph, report };
+}
 
 // src/graph/depthAudit.ts
 var TECH_SIGNAL_RES = [
@@ -238,6 +1216,31 @@ function auditDepthLayers(concepts) {
   });
 }
 
+// src/graph/loExemplars.ts
+var ULO_EXEMPLARS = [
+  // Calibrated against production learning_objectives (UNIVERSAL rows, neutral)
+  "The learner will be able to recall the key concepts, terminology, and characteristics of layers of abstraction.",
+  "The learner will be able to explain how layers of abstraction hide implementation details while exposing essential behavior.",
+  "The learner will be able to explain how a program changes state through statements and control flow.",
+  "The learner will be able to differentiate local from global scope and describe how return values affect data flow.",
+  "The learner will be able to describe the mechanism of a loop, including its condition, step and stopping rule.",
+  "The learner will be able to explain why a representation format must balance readability against processing efficiency."
+];
+var CIO_EXEMPLARS = [
+  // Production CONCEPTUAL_IMPL rows: mechanism behind the clause, Marr 2-Language neutral
+  "The learner will be able to develop a conceptual model that explains the internal mechanism by which the representation produces its effect.",
+  "The learner will be able to compare alternative approaches for the same operation and describe the trade-offs between them.",
+  "The learner will be able to decompose the choice of representation into decisive criteria such as cost, fidelity and tolerance to change.",
+  "The learner will be able to describe the sequence of steps by which a process transforms its input into its output, including the stopping condition."
+];
+var SIO_EXEMPLARS = [
+  // Production SPECIFIC_IMPL style: keyword-bound completable tasks, tech-tagged tier
+  "The learner will be able to use argparse.ArgumentParser with add_subparsers to register add, done and list commands in a Python CLI.",
+  "The learner will be able to define a @dataclass with type hints and a __post_init__ method that raises ValueError on invariant violation.",
+  "The learner will be able to execute parameterized statements via sqlite3.Connection.execute inside a with conn: transaction to perform CRUD on a tasks table.",
+  "The learner will be able to write a pytest test that runs the CLI entry point via subprocess.run and asserts the exit code and printed output."
+];
+
 // src/graph/hierarchicalLoAuthoring.ts
 function excerpt(text, max) {
   const t = (text || "").trim();
@@ -716,58 +1719,6 @@ async function standardizeConcepts(opts) {
 }
 
 // src/graph/knowledgeGraphPipeline.ts
-function detectCycles(concepts) {
-  const cycles = [];
-  const visited = /* @__PURE__ */ new Set();
-  const inStack = /* @__PURE__ */ new Set();
-  const path = [];
-  function dfs(conceptId, prereqMap2) {
-    if (inStack.has(conceptId)) {
-      const cycleStart = path.indexOf(conceptId);
-      if (cycleStart >= 0) {
-        cycles.push([...path.slice(cycleStart), conceptId]);
-      }
-      return;
-    }
-    if (visited.has(conceptId)) return;
-    visited.add(conceptId);
-    inStack.add(conceptId);
-    path.push(conceptId);
-    const prereqs = prereqMap2.get(conceptId) || [];
-    for (const prereq of prereqs) {
-      dfs(prereq, prereqMap2);
-    }
-    path.pop();
-    inStack.delete(conceptId);
-  }
-  const prereqMap = /* @__PURE__ */ new Map();
-  for (const concept of concepts) {
-    prereqMap.set(concept.id, concept.prerequisites || []);
-  }
-  for (const concept of concepts) {
-    if (!visited.has(concept.id)) {
-      dfs(concept.id, prereqMap);
-    }
-  }
-  return cycles;
-}
-function breakCycles(concepts, cycles) {
-  const removed = [];
-  const fixed = concepts.map((c) => ({ ...c, prerequisites: [...c.prerequisites || []] }));
-  for (const cycle of cycles) {
-    if (cycle.length >= 2) {
-      const breaker = cycle[cycle.length - 2];
-      const target = cycle[cycle.length - 1];
-      for (const concept of fixed) {
-        if (concept.id === breaker) {
-          concept.prerequisites = concept.prerequisites.filter((p) => p !== target);
-          removed.push({ from: breaker, to: target });
-        }
-      }
-    }
-  }
-  return { fixed, removed };
-}
 function topologicalSort(concepts) {
   const inDegree = /* @__PURE__ */ new Map();
   const adjacency = /* @__PURE__ */ new Map();
@@ -808,6 +1759,11 @@ async function generateKnowledgeGraph(options) {
     onProgress?.(step, msg);
   };
   log("STEP_1", "Decomposing subject into concepts...");
+  let parsedSyllabus = options.parsedSyllabus;
+  if (!parsedSyllabus && syllabusText) {
+    parsedSyllabus = parseSyllabus(syllabusText);
+    log("STEP_1", `Parsed syllabus: ${parsedSyllabus.units.length} units, ${parsedSyllabus.allTopics.length} topics`);
+  }
   const client = createLlmClient(llmConfig);
   const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "16000", 10);
   let truncatedSyllabus = "";
@@ -819,10 +1775,13 @@ async function generateKnowledgeGraph(options) {
       truncatedSyllabus = syllabusText;
     }
   }
+  const structuredTopicsGuide = parsedSyllabus && parsedSyllabus.allTopics.length > 0 ? `
+STRUCTURED SYLLABUS TOPICS (Every topic MUST map to at least one concept to ensure 100% syllabus coverage):
+` + parsedSyllabus.allTopics.map((t) => `- [${t.unitTitle}] ${t.id}: ${t.title} (Keywords: ${t.keywords.join(", ")})`).join("\n") + "\n" : "";
   const systemPrompt = "You are an expert curriculum designer. Decompose the given subject into a structured knowledge graph with concepts, prerequisites, and problem types.\n\nCRITICAL RULES:\n1. Each concept MUST have the three depth layers, authored against this CONTRACT:\n   - ulo (WHAT + WHY): bound to the CONCEPT's intrinsic NATURE. It explains what the\n     concept is and why it exists \u2014 the problem it solves in principle. It must be\n     TECHNOLOGY-AGNOSTIC: never name a concrete library, API, function, file format,\n     tool or language feature. Typical assessment level: Remember / Understand.\n   - cio (HOW): the MECHANISM \u2014 how the concept works and solves that problem, step\n     by step. Still bound to the concept's nature: more concrete than the ULO, but\n     NOT tied to one specific technology (no concrete API names). CIO capability is\n     assessed INDIRECTLY, through completing contextual work, not in isolation.\n   - sio (IMPLEMENTATION): an array of 2-4 items. EVERY item MUST reference concrete\n     KEYWORDS/technologies (a real API, function, module, file, or named pattern) and\n     describe a completable, context-specific implementation task. Application,\n     Analysis and Creation skills are assessed INDIRECTLY through completing these\n     items. There is NO fixed Bloom ceiling for a layer \u2014 but concreteness MUST\n     strictly increase: SIO more technology-bound than CIO, CIO more concrete than ULO.\n   - prerequisites: concept IDs that must be learned first (MUST NOT create cycles)\n   - problem_types: 2-4 problem types with bloom_level and difficulty. Remember and\n     Understand problem types test the ULO/CIO directly; Apply-and-above types are\n     proxies for SIO completion in context.\n   - techniques: methods, formulas, tools\n2. Prerequisite chains MUST be acyclic (no concept can depend on itself or create a loop)\n3. Concepts should be ordered by prerequisite dependency (topological sort)\n4. Problem types should range from Remember to Apply (not all at same level)\n5. Group concepts into categories (chapters/sections)\n6. ALL text in ENGLISH (even if input is Vietnamese)\n7. NEVER invent concepts not present in the syllabus\n8. Return JSON matching the KnowledgeGraphSchema";
   const userPrompt = `Subject: ${subject}
 ${description ? `Description: ${description}` : ""}
-${truncatedSyllabus ? `Syllabus:
+${structuredTopicsGuide}${truncatedSyllabus ? `Syllabus:
 ${truncatedSyllabus}` : ""}
 ${gradeBand ? `Grade band: ${gradeBand[0]}-${gradeBand[1]}` : ""}
 ${domain ? `Domain: ${domain}` : ""}
@@ -967,13 +1926,13 @@ Return JSON:
     log("STEP_2_5", "Standardized: " + std.decisions.filter((d) => d.decision === "standardized").length + ", proposed new: " + std.decisions.filter((d) => d.decision === "proposed_new").length);
   }
   log("STEP_3", "Checking for prerequisite cycles...");
-  const cycles = detectCycles(concepts);
+  const cycles = detectPrerequisiteCycles(concepts);
   if (cycles.length > 0) {
     log("STEP_3", `Found ${cycles.length} cycle(s) in prerequisite chain \u2014 breaking cycles`);
     for (const cycle of cycles) {
       warnings.push(`Cycle detected: ${cycle.join(" \u2192 ")} \u2014 breaking at weakest edge`);
     }
-    const { fixed, removed } = breakCycles(concepts, cycles);
+    const { fixed, removed } = breakPrerequisiteCycles(concepts, cycles);
     for (let i = 0; i < concepts.length; i++) {
       const fixedConcept = fixed.find((f) => f.id === concepts[i].id);
       if (fixedConcept) {
@@ -1024,16 +1983,21 @@ Return JSON:
     }
   }
   log("STEP_2", `Validated ${concepts.length} concepts, ${categories.length} categories, ${learningPath.length} learning path steps`);
+  const rawGraph = {
+    schema_version: 1,
+    type: "knowledge_graph",
+    subject: result.subject,
+    concepts,
+    categories,
+    learning_path: learningPath
+  };
+  log("STEP_6", "Running Knowledge Graph verification & reverse coverage audit...");
+  const { verifiedGraph, report } = verifyKnowledgeGraph(rawGraph, parsedSyllabus);
+  warnings.push(...report.warnings);
   return {
-    knowledgeGraph: {
-      schema_version: 1,
-      type: "knowledge_graph",
-      subject: result.subject,
-      concepts,
-      categories,
-      learning_path: learningPath
-    },
-    warnings
+    knowledgeGraph: verifiedGraph,
+    warnings,
+    verificationReport: report
   };
 }
 
@@ -1292,6 +2256,6 @@ async function decomposePhases(args) {
   return phases;
 }
 
-export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, cioActionSlug, cioCode, conceptCodeFromName, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode };
-//# sourceMappingURL=chunk-3VVPSRAM.mjs.map
-//# sourceMappingURL=chunk-3VVPSRAM.mjs.map
+export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, auditSyllabusCoverage, breakPrerequisiteCycles, cioActionSlug, cioCode, conceptCodeFromName, createLlmClient, detectPrerequisiteCycles, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, llmChatJson, sioCode, standardStatement, techTagFor, uloCode, verifyKnowledgeGraph, verifyProjectGraph };
+//# sourceMappingURL=chunk-CRN6D4HG.mjs.map
+//# sourceMappingURL=chunk-CRN6D4HG.mjs.map