@thanh01.pmt/domain-kit 0.1.0

package/dist/graph/index.cjs

@@ -0,0 +1,2167 @@
+'use strict';
+
+var fs = require('fs');
+var os = require('os');
+var path = require('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");
+  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((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",
+  swift: "SW",
+  typescript: "TS",
+  javascript: "JV",
+  java: "JAVA",
+  kotlin: "KT",
+  go: "GO",
+  rust: "RUST",
+  csharp: "CS",
+  cpp: "CPP",
+  dart: "DT",
+  php: "PHP",
+  ruby: "RB",
+  sql: "SQL",
+  html: "HTML",
+  css: "CSS"
+};
+function techTagFor(techStack) {
+  const primary = (techStack || "").trim().toLowerCase();
+  for (const [key, tag] of Object.entries(TECH_TAG_MAP)) {
+    if (primary.includes(key)) return tag;
+  }
+  const first = primary.split(/[\s,+/]+/)[0] ?? "";
+  if (!/^[a-z]/.test(first)) return "GEN";
+  return first.length <= 4 ? first.toUpperCase() : first.slice(0, 3).toUpperCase();
+}
+var SMALL_WORDS = /* @__PURE__ */ new Set(["and", "or", "the", "of", "for", "in", "on", "a", "an", "vs"]);
+function conceptCodeFromName(name) {
+  const words = name.replace(/[^A-Za-z0-9]+/g, " ").trim().split(/\s+/).filter((w) => w.length > 0 && !SMALL_WORDS.has(w.toLowerCase()));
+  const base = words.join("_").toUpperCase().replace(/^_+|_+$/g, "").replace(/_{2,}/g, "_");
+  const trimmed = (base || "CONCEPT").slice(0, 60).replace(/_+$/g, "");
+  return trimmed;
+}
+function assignConceptCodes(concepts) {
+  const used = /* @__PURE__ */ new Map();
+  const out = {};
+  for (const c of concepts) {
+    const base = conceptCodeFromName(c.name);
+    const n = (used.get(base) ?? 0) + 1;
+    used.set(base, n);
+    out[c.id] = n === 1 ? base : base + "_" + n;
+  }
+  return out;
+}
+var pad2 = (n) => String(n).padStart(2, "0");
+function uloCode(conceptCode, seq = 1) {
+  return "ULO-" + conceptCode + "-" + pad2(seq);
+}
+var CIO_STOPWORDS = /* @__PURE__ */ new Set([
+  // clause boilerplate
+  "learner",
+  "will",
+  "be",
+  "able",
+  // generic fillers
+  "a",
+  "an",
+  "the",
+  "of",
+  "to",
+  "and",
+  "or",
+  "in",
+  "on",
+  "for",
+  "by",
+  "with",
+  "is",
+  "are",
+  "that",
+  "it",
+  "its",
+  "their",
+  "when",
+  "how",
+  "as",
+  "into",
+  "from"
+]);
+function cioActionSlug(cioText) {
+  const body = cioText.startsWith(LEARNER_CLAUSE) ? cioText.slice(LEARNER_CLAUSE.length) : cioText;
+  const words = body.replace(/[^A-Za-z0-9]+/g, " ").trim().split(/\s+/).map((w) => w.toLowerCase()).filter((w) => w.length > 2 && !CIO_STOPWORDS.has(w));
+  const seen = /* @__PURE__ */ new Set();
+  const picked = [];
+  for (const w of words) {
+    if (!seen.has(w)) {
+      seen.add(w);
+      picked.push(w);
+    }
+    if (picked.length === 3) break;
+  }
+  return (picked.length > 0 ? picked : ["apply"]).join("_").toUpperCase();
+}
+function cioCode(conceptCode, uloSeq, actionSlug) {
+  return "CIO-" + conceptCode + "-" + pad2(uloSeq) + "-" + actionSlug;
+}
+function sioCode(techTag, conceptCode, seq) {
+  return "SIO-" + techTag + "-" + conceptCode + "-" + pad2(seq);
+}
+var LEARNER_CLAUSE = "The learner will be able to ";
+function standardStatement(text) {
+  let body = (text || "").trim().replace(/^the learner (will be able to|can)\s*/i, "").replace(/\s+/g, " ");
+  if (body.length === 0) return "";
+  const firstWord = body.split(" ")[0] ?? "";
+  const looksAcronym = /^[A-Z0-9_.`]+$/.test(firstWord) && firstWord.length > 1;
+  if (!looksAcronym) body = body.charAt(0).toLowerCase() + body.slice(1);
+  body = body.replace(/[.\s]+$/, "");
+  return LEARNER_CLAUSE + body + ".";
+}
+var CONCEPT_CODE_RE = /^[A-Z][A-Z0-9_]*$/;
+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/depthAudit.ts
+var TECH_SIGNAL_RES = [
+  /`[^`]+`/,
+  /\b[a-zA-Z_][A-Za-z0-9_]*\(\)/,
+  // call-with-arguments: Status(enum.Enum), field(default_factory=list)
+  /\b[A-Za-z_][A-Za-z0-9_]*\([^)]+\)/,
+  // attribute access glued to a value: enum.Enum, os.path, tasks.json
+  /[A-Za-z0-9_)\]]\.[A-Za-z_][A-Za-z0-9_]+/,
+  /[a-z]+_[a-z]+/,
+  /[a-z]+[A-Z][A-Za-z]*/,
+  /\.[a-z]{2,4}\b/,
+  /\b(?:API|SDK|JSON|XML|YAML|HTTP|SQL|UUID|URL|DOM|CLI|TUI|CSV|UTF|CRUD|DSL)\b/,
+  // Exception/error class names: Exception, ValueError, CustomError
+  /\b[A-Z][a-zA-Z0-9_]*(?:Error|Exception|Warning|Fault)\b/,
+  // class declarations or references: class Status, static methods on types
+  /\bclass\s+[A-Za-z_][A-Za-z0-9_]*/,
+  // inheritance/derivation mentions: inheriting from Exception, subclass of Base
+  /\b(?:inherit(?:ing|s)?|subclass(?:ing)?|deriv(?:ing|ed|es)?)\s+(?:from|of)\s+[A-Z][A-Za-z0-9_]*/
+];
+var GENERIC_STOP = /* @__PURE__ */ new Set(["e", "g", "i"]);
+function techSignalHits(text) {
+  const hits = [];
+  for (const re of TECH_SIGNAL_RES) {
+    const found = text.match(new RegExp(re.source, "g")) ?? [];
+    for (const m of found) if (!GENERIC_STOP.has(m.toLowerCase())) hits.push(m);
+  }
+  return hits;
+}
+function auditDepthLayers(concepts) {
+  return concepts.map((c) => {
+    const ulo = (c.ulo ?? "").trim();
+    const cio = (c.cio ?? "").trim();
+    const sioItems = (c.sio ?? []).map((s) => (s ?? "").trim()).filter(Boolean);
+    const uloTechSignals = techSignalHits(ulo);
+    const uloHasTechSignals = uloTechSignals.length > 0;
+    const IMPL_VERBS = /\b(implement|refactor|debug|serialize)\b/i;
+    const uloHasImplementationVerbs = IMPL_VERBS.test(ulo);
+    const registryKeywords = (c.keywords ?? []).map((k) => String(k).toLowerCase()).filter((k) => k.length >= 3);
+    const nameTokens = String(c.name ?? "").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 4);
+    const boundToConcept = (s) => {
+      const lower = s.toLowerCase();
+      return registryKeywords.some((k) => lower.includes(k)) || nameTokens.some((w) => lower.includes(w));
+    };
+    const sioUnboundItems = sioItems.filter((s) => {
+      if (techSignalHits(s).length > 0) return false;
+      return !boundToConcept(s);
+    });
+    const conceptKeywords = (c.keywords ?? []).map((k) => k.toLowerCase()).filter(Boolean);
+    const sioOffConceptItems = conceptKeywords.length > 0 ? sioItems.filter((s) => !boundToConcept(s)) : [];
+    const COMPLETABLE = /\b(build|create|implement|write|configure|add|use|apply|display|store|load|save|handle|parse|validate|test|register|compute|generate|print|format|convert|extend|define|execute|run|read|fetch|wrap|log|call|raise|install|import|export|declare|embed|model|represent|override|customize|enforce|mock|assert|query|index|cache|stream|split|join|strip|encode|decode|traverse|measure|evaluate|benchmark|diagnose|demonstrate|verify|organize|structure|choose|select|compare|distinguish|attach|annotate|expose|accept|manage|group|sort|filter|map|reduce|catch|throw|migrate|inspect|trace|parameterize|construct|design|capture)\b/i;
+    const sioNotCompletable = sioItems.filter((s) => !COMPLETABLE.test(s) && !/`[^`]+`/.test(s));
+    const density = (text) => {
+      if (!text) return 0;
+      return techSignalHits(text).length / Math.max(1, text.split(/\s+/).length) * 100;
+    };
+    const dUlo = density(ulo);
+    density(cio);
+    const dSio = sioItems.length > 0 ? Math.max(...sioItems.map(density)) : 0;
+    const concretenessIncreases = dSio > dUlo;
+    const clauseOk = ulo.startsWith(LEARNER_CLAUSE) && cio.startsWith(LEARNER_CLAUSE) && sioItems.every((t) => t.startsWith(LEARNER_CLAUSE));
+    const codeIssues = [];
+    const conceptCode = c.code;
+    if (conceptCode !== void 0 && !CONCEPT_CODE_RE.test(conceptCode)) codeIssues.push("concept code not UPPER_SNAKE: " + conceptCode);
+    const uloCodeVal = c.ulo_code;
+    if (uloCodeVal !== void 0 && uloCodeVal !== "" && !ULO_CODE_RE.test(uloCodeVal)) codeIssues.push("ULO code malformed: " + uloCodeVal);
+    const cioCodeVal = c.cio_code;
+    if (cioCodeVal !== void 0 && cioCodeVal !== "" && !CIO_CODE_RE.test(cioCodeVal)) codeIssues.push("CIO code malformed: " + cioCodeVal);
+    const sioCodeVals = c.sio_codes;
+    if (sioCodeVals !== void 0) {
+      if (sioCodeVals.length !== sioItems.length) codeIssues.push("SIO codes count mismatch");
+      for (const sc of sioCodeVals) if (!SIO_CODE_RE.test(sc)) codeIssues.push("SIO code malformed: " + sc);
+    }
+    const codesOk = codeIssues.length === 0;
+    const passed = !uloHasTechSignals && !uloHasImplementationVerbs && sioUnboundItems.length === 0 && sioOffConceptItems.length === 0 && sioNotCompletable.length === 0 && concretenessIncreases && clauseOk && codesOk;
+    return {
+      conceptId: c.id,
+      uloHasTechSignals,
+      uloTechSignals,
+      uloHasImplementationVerbs,
+      sioAllKeywordBound: sioUnboundItems.length === 0,
+      sioUnboundItems,
+      sioConceptKeywordBound: sioOffConceptItems.length === 0,
+      sioOffConceptItems,
+      sioAllCompletable: sioNotCompletable.length === 0,
+      sioNotCompletable,
+      concretenessIncreases,
+      clauseOk,
+      codesOk,
+      codeIssues,
+      passed
+    };
+  });
+}
+
+// src/graph/hierarchicalLoAuthoring.ts
+function excerpt(text, max) {
+  const t = (text || "").trim();
+  return t.length > max ? t.slice(0, max) + "..." : t;
+}
+async function chatJson(client, system, user) {
+  const r = await client.chat(
+    [{ role: "system", content: system }, { role: "user", content: user }],
+    { temperature: 0.1, maxTokens: parseInt(process.env.KG_MAX_TOKENS || "65536", 10) }
+  );
+  return parseJsonFromLlm(r.content);
+}
+var LO_BATCH_SIZE = 6;
+function chunkConcepts(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+var JSON_ONLY = "Return EXACTLY JSON. No markdown, no explanations.";
+async function authorDepthLayersHierarchically(client, concepts, techStack, warnings) {
+  const uloByConcept = {};
+  const cioByConcept = {};
+  const sioByConcept = {};
+  concepts.map((c) => "- " + c.id + ": " + c.name + (c.description ? " \u2014 " + excerpt(c.description, 160) : "")).join("\n");
+  const uloSystem = [
+    "You are a Curriculum Design Expert writing Universal Learning Objectives (ULO).",
+    "",
+    "ULO = Computational Tier: the CORE COMPETENCY \u2014 WHAT the concept is and WHY it exists \u2014",
+    "completely independent of any technology, language, framework, library, file format or tool.",
+    "",
+    "Rules:",
+    "1. NEVER mention a concrete technology, API, library, file name or syntax in a ULO.",
+    "2. Bind the ULO to the concept intrinsic nature: the problem it solves in principle.",
+    "3. Typical assessment level: Remember or Understand. Use pragmatic, measurable verbs",
+    "   (Explain, Differentiate, Identify, Describe) instead of Know/Understand/Summarize.",
+    "4. Cognitive Ceiling: do NOT force Analyze/Evaluate/Create ULOs \u2014 if the concept is",
+    "   foundational, its core competency is low-level. Higher levels are exercised later",
+    "   INDIRECTLY through implementation work, not in the ULO itself.",
+    "5. One ULO per concept; 1-2 sentences covering WHAT + WHY.",
+    "6. Statement form (mandatory): every ULO MUST read 'The learner will be able to ...' \u2014",
+    "   a lowercase actionable verb follows the clause (explain ..., differentiate ...).",
+    "   Do not prefix any other phrasing.",
+    "",
+    "Approved style exemplars (production bank):",
+    ULO_EXEMPLARS.map((e) => "- " + e).join("\n"),
+    "",
+    JSON_ONLY
+  ].join("\n");
+  for (const batch of chunkConcepts(concepts, LO_BATCH_SIZE)) {
+    const batchList = batch.map((c) => "- " + c.id + " (" + c.name + ")" + (c.description ? ": " + excerpt(c.description, 160) : "")).join("\n");
+    const batchUser = "Concepts:\n" + batchList + '\n\nReturn JSON:\n{"ulos":[{"concept_id":"C1","ulo":"..."}]}';
+    const uloRes = await chatJson(client, uloSystem, batchUser);
+    for (const u of uloRes.ulos ?? []) {
+      if (u.concept_id && u.ulo) uloByConcept[u.concept_id] = standardStatement(u.ulo);
+    }
+  }
+  for (const c of concepts) {
+    if (!uloByConcept[c.id]) {
+      warnings.push("Phase A: no ULO generated for " + c.id + " \u2014 kept empty (audit will fail)");
+      uloByConcept[c.id] = "";
+    }
+  }
+  concepts.map((c) => "- " + c.id + " (" + c.name + "): " + uloByConcept[c.id]).join("\n");
+  const cioSystem = [
+    "You are a Curriculum Design Expert writing Concept-level Instructional Objectives (CIO).",
+    "",
+    "CIO = Algorithmic Tier: the MECHANISM \u2014 HOW the concept works, step by step, at a",
+    "procedural level. CIOs are derived from approved ULOs.",
+    "",
+    "Rules:",
+    "1. Still technology-agnostic: describe the neutral pattern/approach WITHOUT concrete",
+    "   API names, libraries, file formats or syntax.",
+    "2. Marr 2-Language Test: the CIO must read as true and implementable regardless of",
+    "   whether the learner uses Python, Swift, JavaScript or any other language. If it",
+    "   only makes sense in one language, rewrite it more neutrally.",
+    "3. More concrete than the ULO: reference stages, conditions, ordering or trade-offs",
+    "   of the underlying process.",
+    "4. One CIO per concept; 1-3 sentences describing the mechanism.",
+    "5. Statement form (mandatory): every CIO MUST read 'The learner will be able to ...' \u2014",
+    "   the mechanism is described after the clause.",
+    "",
+    "Approved style exemplars (production bank):",
+    CIO_EXEMPLARS.map((e) => "- " + e).join("\n"),
+    "",
+    JSON_ONLY
+  ].join("\n");
+  for (const batch of chunkConcepts(concepts, LO_BATCH_SIZE)) {
+    new Set(batch.map((c) => c.id));
+    const batchUloContext = batch.map((c) => "- " + c.id + " (" + c.name + "): " + (uloByConcept[c.id] || "(missing)")).join("\n");
+    const batchCioUser = "Approved ULOs:\n" + batchUloContext + '\n\nReturn JSON:\n{"cios":[{"concept_id":"C1","cio":"..."}]}';
+    const cioRes = await chatJson(client, cioSystem, batchCioUser);
+    for (const x of cioRes.cios ?? []) {
+      if (x.concept_id && x.cio) cioByConcept[x.concept_id] = standardStatement(x.cio);
+    }
+  }
+  for (const c of concepts) {
+    if (!cioByConcept[c.id]) {
+      warnings.push("Phase B: no CIO generated for " + c.id + " \u2014 kept empty (audit will fail)");
+      cioByConcept[c.id] = "";
+    }
+  }
+  concepts.map((c) => "- " + c.id + " (" + c.name + "): CIO=" + cioByConcept[c.id] + " | ULO=" + uloByConcept[c.id]).join("\n");
+  const sioSystem = [
+    "You are a Curriculum Design Expert writing Specific Instructional Objectives (SIO).",
+    "",
+    "SIO = Implementation Tier: completable, context-specific implementation tasks derived",
+    "from approved CIOs, bound to the TARGET technology of the course.",
+    "",
+    "Rules:",
+    "1. EVERY SIO item MUST name concrete keywords/technologies: a real API, function,",
+    "   decorator, module, class, file or command of the target technology.",
+    "2. Each item is a completable task: an actionable verb + the concrete construct + the",
+    "   context where it is used. Application/Analysis/Creation skills are assessed",
+    "   INDIRECTLY through completing these tasks \u2014 there is no fixed Bloom ceiling.",
+    "   MACHINE CHECK: every item MUST contain at least one ACTION VERB from this whitelist",
+    "   (build, create, implement, write, configure, add, use, apply, display, store, load,",
+    "   save, handle, parse, validate, test, register, compute, generate, print, format,",
+    "   convert, extend, define, execute, run, read, fetch, wrap, log, call, raise, install,",
+    "   import, export, declare, embed, model, represent, override, customize, enforce, mock,",
+    "   assert, query, index, cache, stream, split, join, strip, encode, decode, traverse,",
+    "   measure, evaluate, benchmark, diagnose, demonstrate, verify, organize, structure,",
+    "   choose, select, compare, distinguish, attach, annotate, expose, accept, manage, group,",
+    "   sort, filter, map, reduce, catch, throw, migrate, inspect, trace, parameterize,",
+    "   construct, design, capture) \u2014 OR wrap the concrete construct in backticks.",
+    "   Items with abstract verbs (understand, learn, know, grasp, appreciate, explore) and",
+    "   no backtick construct FAIL the audit. Prefer starting the task phrase with the verb.",
+    "3. 2-3 items per concept, each referencing a DIFFERENT concrete construct.",
+    "4. Statement form (mandatory): every SIO MUST read 'The learner will be able to ...' \u2014",
+    "   the concrete task follows the clause.",
+    "",
+    "Approved style exemplars (production bank):",
+    SIO_EXEMPLARS.map((e) => "- " + e).join("\n"),
+    "",
+    JSON_ONLY
+  ].join("\n");
+  concepts.map((c) => "- " + c.id + " (" + c.name + "): " + ((c.keywords ?? []).slice(0, 10).join(", ") || "(none listed \u2014 use concrete constructs of " + techStack + ")")).join("\n");
+  for (const batch of chunkConcepts(concepts, LO_BATCH_SIZE)) {
+    const batchKw = batch.map((c) => "- " + c.id + " (" + c.name + "): " + ((c.keywords ?? []).slice(0, 10).join(", ") || "(none listed \u2014 use concrete constructs of " + techStack + ")")).join("\n");
+    const batchCioCtx = batch.map((c) => "- " + c.id + " (" + c.name + "): CIO=" + (cioByConcept[c.id] || "(missing)") + " | ULO=" + (uloByConcept[c.id] || "(missing)")).join("\n");
+    const batchSioUser = [
+      "Target technology: " + techStack,
+      "",
+      "Concept keywords (each SIO item MUST contain at least one of its concept's keywords):",
+      batchKw,
+      "",
+      "Approved CIOs and ULOs:",
+      batchCioCtx,
+      "",
+      "Return JSON:",
+      '{"sios":[{"concept_id":"C1","sio":["...","..."]}]}'
+    ].join("\n");
+    const sioRes = await chatJson(client, sioSystem, batchSioUser);
+    for (const x of sioRes.sios ?? []) {
+      if (x.concept_id && Array.isArray(x.sio)) sioByConcept[x.concept_id] = x.sio.map((item) => standardStatement(String(item)));
+    }
+  }
+  for (const c of concepts) {
+    if (!sioByConcept[c.id] || sioByConcept[c.id].length === 0) {
+      warnings.push("Phase C: no SIO generated for " + c.id + " \u2014 kept empty (audit will fail)");
+      sioByConcept[c.id] = [];
+    }
+  }
+  concepts.map((c) => c.id);
+  const auditOnce = () => auditDepthLayers(concepts.map((c) => ({
+    id: c.id,
+    name: c.name,
+    keywords: c.keywords ?? [],
+    ulo: uloByConcept[c.id],
+    cio: cioByConcept[c.id],
+    sio: sioByConcept[c.id]
+  })));
+  let audits = auditOnce();
+  const repairRound = async (round) => {
+    const failingNow = audits.filter((a) => !a.passed);
+    if (failingNow.length === 0) return false;
+    if (round > 1) warnings.push("Depth audit repair round " + round + ": " + failingNow.length + " concept(s) still failing");
+    const failing = failingNow;
+    {
+      warnings.push("Depth audit: " + failing.length + "/" + concepts.length + " concepts failed first audit \u2014 targeted repair");
+      const repairTargets = failing.map((a) => {
+        const c = concepts.find((x) => x.id === a.conceptId);
+        const issues = [];
+        if (a.uloHasTechSignals) issues.push("ULO names concrete technology (remove: " + a.uloTechSignals.join(", ") + ")");
+        if (a.uloHasImplementationVerbs) issues.push("ULO reads as an implementation task (rewrite as WHAT+WHY competency)");
+        for (const item of a.sioUnboundItems) issues.push("SIO not keyword-bound: " + excerpt(item, 120));
+        for (const item of a.sioOffConceptItems) issues.push("SIO does not reference any of this concept's keywords (" + (c?.keywords ?? []).join(", ") + "): " + excerpt(item, 120));
+        for (const item of a.sioNotCompletable) issues.push("SIO not a completable task: " + excerpt(item, 120));
+        if (!a.concretenessIncreases) issues.push("SIO is not more concrete than the ULO \u2014 bind it to concrete constructs");
+        return {
+          concept_id: a.conceptId,
+          name: c?.name ?? a.conceptId,
+          keywords: c?.keywords ?? [],
+          current: { ulo: uloByConcept[a.conceptId], cio: cioByConcept[a.conceptId], sio: sioByConcept[a.conceptId] },
+          issues
+        };
+      });
+      const repairSystem = [
+        "You repair depth-layer learning objectives that failed a deterministic contract audit.",
+        "For each concept, rewrite ONLY the layers mentioned in issues, keeping the others as-is.",
+        "Contract:",
+        "- ULO: WHAT+WHY, concept-bound, technology-agnostic, Remember/Understand verbs.",
+        "- CIO: HOW mechanism, technology-agnostic, more concrete than ULO, Marr 2-Language neutral.",
+        "- SIO: keyword-bound completable implementation tasks naming real constructs of " + techStack + ".",
+        "- BINDING RULE: every SIO item must contain at least one of the concept's listed keywords VERBATIM (copy the exact keyword text into the sentence).",
+        "- COMPLETABILITY RULE: every SIO item must contain an actionable verb (build, create, implement, write, configure, parse, validate, handle, store, load, run, read, fetch, display, generate, format, convert, test, debug, trace, measure, design, structure, select, filter, sort, map, reduce, catch, throw, migrate, deploy, query, index, cache, stream, inspect) or wrap a concrete construct in backticks \u2014 abstract verbs (understand, learn, know, grasp, explore, appreciate) always fail.",
+        "",
+        JSON_ONLY
+      ].join("\n");
+      const repairUser = [
+        "Failing concepts:",
+        JSON.stringify(repairTargets, null, 2),
+        "",
+        "Return the FULL repaired set for these concepts in the same 3-layer JSON shape:",
+        '{"repairs":[{"concept_id":"C1","ulo":"...","cio":"...","sio":["..."]}]}'
+      ].join("\n");
+      try {
+        const repairRes = await chatJson(client, repairSystem, repairUser);
+        for (const r of repairRes.repairs ?? []) {
+          if (!r.concept_id) continue;
+          if (r.ulo) uloByConcept[r.concept_id] = standardStatement(r.ulo);
+          if (r.cio) cioByConcept[r.concept_id] = standardStatement(r.cio);
+          if (Array.isArray(r.sio) && r.sio.length > 0) sioByConcept[r.concept_id] = r.sio.map((t) => standardStatement(String(t)));
+        }
+        audits = auditOnce();
+      } catch (err) {
+        warnings.push("Depth repair round failed: " + (err instanceof Error ? err.message : String(err)));
+      }
+    }
+    return audits.every((a) => a.passed);
+  };
+  for (let round = 1; round <= 2; round++) {
+    const allPass = await repairRound(round);
+    if (allPass) break;
+  }
+  const stillFailing = audits.filter((a) => !a.passed);
+  if (stillFailing.length > 0) {
+    try {
+      const { mkdirSync: mkdirSync2, writeFileSync: writeFileSync2 } = await import('fs');
+      const dumpDir = (await import('os')).tmpdir() + "/domain-kit-debug/";
+      mkdirSync2(dumpDir, { recursive: true });
+      writeFileSync2(dumpDir + "depth-audit-debug.json", JSON.stringify(
+        stillFailing.map((a) => ({ audit: a, ulo: uloByConcept[a.conceptId], cio: cioByConcept[a.conceptId], sio: sioByConcept[a.conceptId] })),
+        null,
+        2
+      ));
+    } catch {
+    }
+    const detail = stillFailing.map((a) => a.conceptId + "[" + (a.uloHasTechSignals ? "ulo-tech " : "") + (a.uloHasImplementationVerbs ? "ulo-impl " : "") + (a.sioUnboundItems.length ? "sio-unbound " : "") + (a.sioNotCompletable.length ? "sio-incomplete" : "") + "]").join(", ");
+    throw new Error(
+      "Depth-layer contract audit failed after repair for: " + detail + " \u2014 regenerate or fix the prompt contract (fail-closed, no silent fallback)"
+    );
+  }
+  return { uloByConcept, cioByConcept, sioByConcept, audits, warnings };
+}
+function cell(v) {
+  return (v || "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+function loadKnowledgeTreeCatalog(tsvPath) {
+  const text = fs.readFileSync(tsvPath, "utf8");
+  const lines = text.split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length === 0) throw new Error("Knowledge tree TSV is empty: " + tsvPath);
+  const header = lines[0].split("	").map((h) => h.trim());
+  const col = (name) => header.indexOf(name);
+  const iT = col("item_type");
+  const iC = col("code");
+  const iN = col("name");
+  const iD = col("description");
+  const iCat = col("category_codes");
+  const iTpc = col("topic_codes");
+  const iPre = col("prerequisite_concept_codes");
+  const iKw = col("keywords");
+  for (const [name, idx] of [["item_type", iT], ["code", iC], ["name", iN]]) {
+    if (idx < 0) throw new Error("Knowledge tree TSV missing column: " + name);
+  }
+  const categories = /* @__PURE__ */ new Map();
+  const topics = /* @__PURE__ */ new Map();
+  const concepts = [];
+  for (const line of lines.slice(1)) {
+    const c = line.split("	");
+    const type = (c[iT] || "").trim();
+    const code = (c[iC] || "").trim();
+    const name = (c[iN] || "").trim();
+    if (!code || !name) continue;
+    if (type === "CATEGORY") categories.set(code, name);
+    if (type === "TOPIC") topics.set(code, { name, categoryCodes: cell(c[iCat]) });
+    if (type !== "CONCEPT") continue;
+    const topicCodes = cell(c[iTpc]);
+    const categoryCodes = /* @__PURE__ */ new Set();
+    for (const t of topicCodes) for (const cc of topics.get(t)?.categoryCodes || []) categoryCodes.add(cc);
+    concepts.push({
+      code,
+      name,
+      description: (c[iD] || "").trim(),
+      keywords: cell(c[iKw]),
+      topicCodes,
+      categoryCodes: [...categoryCodes],
+      prerequisiteCodes: cell(c[iPre])
+    });
+  }
+  if (concepts.length === 0) throw new Error("Knowledge tree TSV has no CONCEPT rows: " + tsvPath);
+  return { path: tsvPath, concepts, categories, topics };
+}
+function tokens(s) {
+  return new Set(
+    s.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
+  );
+}
+function filterBySelection(catalog, selectedCategories, selectedTopics, analysisConcepts, maxConcepts = 120) {
+  const tps = new Set(selectedTopics.map((c) => c.trim().toUpperCase()).filter(Boolean));
+  const cats = new Set(selectedCategories.map((c) => c.trim().toUpperCase()).filter(Boolean));
+  const probe = analysisConcepts.map((c) => tokens(c.name + " " + c.keywords.join(" ")));
+  const probeAll = /* @__PURE__ */ new Set();
+  for (const p of probe) for (const w of p) probeAll.add(w);
+  const inSelection = (tc) => tc.topicCodes.some((t) => tps.has(t)) || tc.categoryCodes.some((c) => cats.has(c));
+  const overlapScore = (tc) => {
+    const tcTok = tokens(tc.name + " " + tc.description.slice(0, 300) + " " + tc.keywords.join(" "));
+    let overlap = 0;
+    for (const w of tcTok) if (probeAll.has(w)) overlap++;
+    const kwDirect = tc.keywords.filter((k) => {
+      const kl = k.toLowerCase();
+      return [...probeAll].some((w) => w === kl || w.length >= 5 && kl.includes(w));
+    }).length;
+    return overlap * 2 + kwDirect * 3;
+  };
+  const kept = catalog.concepts.filter((tc) => inSelection(tc) || overlapScore(tc) >= 6);
+  return kept.map((tc) => ({ tc, s: overlapScore(tc) })).sort((a, b) => b.s - a.s).slice(0, maxConcepts).map((x) => x.tc);
+}
+function renderShortlist(shortlist) {
+  return shortlist.map((tc) => "- " + tc.code + " | " + tc.name + " | kw: " + tc.keywords.slice(0, 8).join(", ") + (tc.prerequisiteCodes.length ? " | prereqs: " + tc.prerequisiteCodes.join(",") : "")).join("\n");
+}
+function renderCategoryTopicIndex(catalog) {
+  const topicToConcepts = /* @__PURE__ */ new Map();
+  for (const tc of catalog.concepts) for (const t of tc.topicCodes) topicToConcepts.set(t, (topicToConcepts.get(t) || 0) + 1);
+  const byCat = /* @__PURE__ */ new Map();
+  for (const [code, info] of catalog.topics) {
+    for (const cat of info.categoryCodes) {
+      const arr = byCat.get(cat) || [];
+      arr.push(code + " " + info.name + " (" + (topicToConcepts.get(code) || 0) + " concepts)");
+      byCat.set(cat, arr);
+    }
+  }
+  const out = [];
+  for (const [code, name] of catalog.categories) {
+    out.push("CATEGORY " + code + " \u2014 " + name);
+    for (const t of byCat.get(code) || []) out.push("    TOPIC: " + t);
+  }
+  return out.join("\n");
+}
+var JSON_ONLY2 = "Return ONLY a JSON object, no markdown fences, no commentary.";
+function parseJsonBlock(text) {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new Error("LLM standardization response has no JSON object");
+  return JSON.parse(text.slice(start, end + 1));
+}
+async function standardizeConcepts(opts) {
+  const { client, catalog, techStack = "python", proposalsPath } = opts;
+  const log = opts.onProgress ?? (() => {
+  });
+  const warnings = [];
+  const hasTopics = catalog.topics.size > 0;
+  const selSystem = [
+    "You pre-select relevant areas of an institutional knowledge tree before a detailed concept alignment pass.",
+    hasTopics ? "Given the analysis concepts, pick the TOPICS that could contain matching concepts. Concepts are filed under topics, so topics are the filter dimension." : "Given the analysis concepts, pick the CATEGORIES that could contain matching concepts.",
+    "- Be generous: missing a relevant topic corrupts the alignment; an extra topic only costs attention.",
+    "- Only codes that appear in the index are valid.",
+    JSON_ONLY2
+  ].join("\n");
+  const selUser = [
+    "ANALYSIS CONCEPTS:",
+    opts.concepts.map((c) => "- " + c.name + ": " + c.description.slice(0, 160)).join("\n"),
+    "",
+    "KNOWLEDGE TREE INDEX:",
+    renderCategoryTopicIndex(catalog),
+    "",
+    hasTopics ? 'Return JSON: {"relevant_topics":["TOPIC_CODE"]}' : 'Return JSON: {"relevant_categories":["CATEGORY_CODE"]}'
+  ].join("\n");
+  const selRes = await client.chat(
+    [{ role: "system", content: selSystem }, { role: "user", content: selUser }],
+    { temperature: 0, maxTokens: 4096 }
+  );
+  const sel = parseJsonBlock(selRes.content);
+  const selTps = hasTopics ? (sel.relevant_topics || []).map(String).filter(Boolean) : [];
+  const selCats = hasTopics ? [] : (sel.relevant_categories || []).map(String).filter(Boolean);
+  log("STEP_2_5", "LLM relevance pre-selection (" + (hasTopics ? "topics" : "categories") + "): " + (hasTopics ? selTps.join(",") : selCats.join(",")));
+  const shortlist = filterBySelection(catalog, selCats, selTps, opts.concepts);
+  log("STEP_2_5", "Filtered tree concepts: " + shortlist.length + "/" + catalog.concepts.length + " shortlisted for alignment");
+  if (shortlist.length === 0) throw new Error("Topic/category pre-selection eliminated every tree concept \u2014 fail-closed");
+  const system = [
+    "You align auto-derived learning concepts with an institutional knowledge tree.",
+    "For EACH input concept decide exactly one of:",
+    `  1. "standardized" - the concept teaches the SAME underlying knowledge as one tree concept. Applying a tree concept inside a specific product context (e.g. "File-based persistence in a CLI app") is STILL the tree concept if the core knowledge matches. Set tree_code to that concept's code.`,
+    "     Adopt the tree's terminology. Only propose new when the tree genuinely has NO concept teaching that knowledge (broader AND narrower both fail).",
+    '  2. "proposed_new" - no tree concept covers it at the same granularity. Propose an UPPER_SNAKE_CASE code (descriptive, stable, max 5 words) and a one-sentence definition.',
+    "     If between 1 and 3 tree concepts are CLOSE but not exact, list their codes in possible_tree_matches for human review.",
+    `For a "standardized" decision ALSO return "adopted_keywords": the subset of that tree concept's keywords (from the shortlist) that make sense for the course TECH STACK. Drop keywords that name tooling from other ecosystems (e.g. JS test runners for a Python course) \u2014 keep conceptual keywords even when spelled generically. Maximum 8, ordered most-relevant first.`,
+    "Rules:",
+    "- Judge by MEANING (definition + keywords), not by string similarity.",
+    '- COVERAGE RULE: a "standardized" match must cover ALL primary dimensions of the input concept \u2014 every distinct aspect named in its title or description. A tree concept covering only ONE of several aspects (e.g. "interpreting error messages" for a concept about error handling AND user experience) is a PARTIAL match: decide "proposed_new" and list that tree code in possible_tree_matches.',
+    "- Context-specific wording does NOT make a new concept: new concept = knowledge absent from the tree, not knowledge applied elsewhere.",
+    "- Every input concept MUST receive exactly one decision. Never merge two input concepts into one tree code.",
+    "- Prefer proposed_new over a wrong standardized match: a false match corrupts the curriculum.",
+    JSON_ONLY2
+  ].join("\n");
+  const user = [
+    "TECH STACK: " + techStack,
+    "",
+    "ANALYSIS CONCEPTS (to standardize):",
+    JSON.stringify(opts.concepts.map((c) => ({ id: c.id, name: c.name, description: c.description.slice(0, 300), keywords: c.keywords.slice(0, 12) })), null, 1),
+    "",
+    "KNOWLEDGE TREE SHORTLIST (pre-filtered, " + shortlist.length + " candidate concepts):",
+    renderShortlist(shortlist),
+    "",
+    'Return JSON: {"decisions":[{"id":"<input id>","decision":"standardized","tree_code":"TREE_CODE","adopted_keywords":["kw1","kw2"],"note":"one sentence"},',
+    '  {"id":"<input id>","decision":"proposed_new","proposed_code":"PROPOSED_CODE","proposed_definition":"...","possible_tree_matches":["CODE"]}]}'
+  ].join("\n");
+  const res = await client.chat(
+    [{ role: "system", content: system }, { role: "user", content: user }],
+    { temperature: 0, maxTokens: 8192 }
+  );
+  log("STEP_2_5", "Standardization response received (provider " + res.provider + ")");
+  const parsed = parseJsonBlock(res.content);
+  const decisions = parsed.decisions ?? [];
+  const byId = new Map(decisions.map((d) => [String(d.id), d]));
+  const finalDecisions = [];
+  const proposals = [];
+  for (const c of opts.concepts) {
+    const d = byId.get(c.id);
+    if (!d || d.decision !== "standardized" && d.decision !== "proposed_new") {
+      throw new Error("Concept " + c.id + " (" + c.name + ") has no standardization decision \u2014 fail-closed");
+    }
+    if (d.decision === "standardized") {
+      const tc = catalog.concepts.find((x) => x.code === d.tree_code);
+      if (!tc) throw new Error("Concept " + c.id + " standardized to unknown tree code " + d.tree_code + " \u2014 fail-closed");
+      const treeKw = new Set(tc.keywords.map((k) => k.toLowerCase()));
+      const adopted = (d.adopted_keywords || []).map((k) => String(k)).filter((k) => {
+        if (treeKw.has(k.toLowerCase())) return true;
+        throw new Error("Concept " + c.id + ' adopted keyword "' + k + '" not in tree concept ' + tc.code + " \u2014 fail-closed");
+      });
+      if (tc.keywords.length > 0 && adopted.length === 0) {
+        throw new Error("Concept " + c.id + " standardized to " + tc.code + " without adopted_keywords \u2014 fail-closed");
+      }
+      finalDecisions.push({ ...d, id: c.id, tree_code: tc.code, adopted_keywords: adopted });
+      warnings.push("Concept " + c.id + " standardized as " + tc.code + " (" + tc.name + "), adopted keywords: " + adopted.join(", ") + (d.note ? " \u2014 " + d.note : ""));
+    } else {
+      const code = (d.proposed_code || "").toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+      if (!/^[A-Z][A-Z0-9_]*$/.test(code)) {
+        throw new Error("Concept " + c.id + ' proposed invalid code "' + d.proposed_code + '" \u2014 fail-closed');
+      }
+      finalDecisions.push({ ...d, id: c.id, proposed_code: code });
+      proposals.push({
+        code,
+        name: c.name,
+        description: d.proposed_definition || c.description.slice(0, 300),
+        keywords: c.keywords,
+        subject_codes: "PY",
+        category_codes: "",
+        topic_codes: "",
+        prerequisite_concept_codes: [],
+        status: "proposed",
+        source_concept_id: c.id,
+        possible_tree_matches: (d.possible_tree_matches || []).filter(Boolean)
+      });
+      warnings.push("Concept " + c.id + " proposed as NEW: " + code + (d.possible_tree_matches?.length ? " (near matches: " + d.possible_tree_matches.join(", ") + ")" : ""));
+    }
+  }
+  const outPath = proposalsPath || path.join(os.tmpdir(), "domain-kit-debug", "concept-proposals.json");
+  try {
+    fs.mkdirSync(outPath.slice(0, outPath.lastIndexOf("/")), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify({ generated_at: (/* @__PURE__ */ new Date()).toISOString(), proposals }, null, 2));
+    log("STEP_2_5", "Proposals written: " + proposals.length + " -> " + outPath);
+  } catch (e) {
+    warnings.push("Could not write proposals artifact: " + (e instanceof Error ? e.message : String(e)));
+  }
+  return { decisions: finalDecisions, proposals, warnings, shortlistSize: shortlist.length, catalogSize: catalog.concepts.length };
+}
+
+// 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();
+  for (const concept of concepts) {
+    inDegree.set(concept.id, 0);
+    adjacency.set(concept.id, []);
+  }
+  for (const concept of concepts) {
+    for (const prereq of concept.prerequisites || []) {
+      adjacency.get(prereq)?.push(concept.id);
+      inDegree.set(concept.id, (inDegree.get(concept.id) || 0) + 1);
+    }
+  }
+  const queue = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    sorted.push(current);
+    for (const neighbor of adjacency.get(current) || []) {
+      const newDegree = (inDegree.get(neighbor) || 1) - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) queue.push(neighbor);
+    }
+  }
+  if (sorted.length !== concepts.length) {
+    console.warn(`[WARN] Topological sort incomplete: ${sorted.length}/${concepts.length} concepts sorted`);
+  }
+  return sorted;
+}
+async function generateKnowledgeGraph(options) {
+  const { subject, description, syllabusText, gradeBand, domain, techStack, llmConfig, onProgress } = options;
+  const warnings = [];
+  const log = (step, msg) => {
+    console.log(`[KG-${step}] ${msg}`);
+    onProgress?.(step, msg);
+  };
+  log("STEP_1", "Decomposing subject into concepts...");
+  const client = createLlmClient(llmConfig);
+  const maxSyllabusChars = parseInt(process.env.KG_MAX_SYLLABUS_CHARS || "16000", 10);
+  let truncatedSyllabus = "";
+  if (syllabusText) {
+    if (syllabusText.length > maxSyllabusChars) {
+      truncatedSyllabus = syllabusText.slice(0, maxSyllabusChars);
+      warnings.push(`Syllabus truncated from ${syllabusText.length} to ${maxSyllabusChars} chars \u2014 may miss some concepts`);
+    } else {
+      truncatedSyllabus = syllabusText;
+    }
+  }
+  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:
+${truncatedSyllabus}` : ""}
+${gradeBand ? `Grade band: ${gradeBand[0]}-${gradeBand[1]}` : ""}
+${domain ? `Domain: ${domain}` : ""}
+
+Return JSON:
+{
+  "subject": {
+    "id": "${subject.toLowerCase().replace(/\s+/g, "-").slice(0, 30)}",
+    "name": "${subject}",
+    "description": "...",
+    "domain": "${domain || "other"}",
+    "grade_band": ${gradeBand ? `[${gradeBand[0]}, ${gradeBand[1]}]` : "[6, 12]"}
+  },
+  "concepts": [
+    {
+      "id": "C1",
+      "name": "Concept name",
+      "description": "Brief description",
+      "category": "category_id",
+      "ulo": "WHAT + WHY in technology-agnostic language: what the concept is and the problem it exists to solve. No library/API/tool names.",
+      "cio": "HOW the mechanism works, still technology-agnostic but more concrete than the ULO.",
+      "sio": ["Concrete task naming a REAL API/function/module/file from the target technology, completable end to end", "Another technology-bound task using a different concrete keyword"],
+      "prerequisites": [],
+      "estimated_minutes": 30,
+      "problem_types": [
+        {
+          "id": "PT-C1-01",
+          "name": "Problem type name",
+          "description": "What this problem type tests",
+          "bloom_level": "Remember",
+          "difficulty": "easy",
+          "estimated_minutes": 10
+        }
+      ],
+      "techniques": ["technique 1", "technique 2"],
+      "common_mistakes": ["mistake 1"]
+    }
+  ],
+  "categories": [
+    {
+      "id": "cat1",
+      "name": "Category name",
+      "description": "Category description",
+      "concept_ids": ["C1", "C2"],
+      "order": 1
+    }
+  ],
+  "learning_path": [
+    {"concept_id": "C1", "order": 1, "depends_on": []},
+    {"concept_id": "C2", "order": 2, "depends_on": ["C1"]}
+  ]
+}`;
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: parseInt(process.env.KG_MAX_TOKENS || "65536", 10)
+  });
+  log("STEP_2", "Validating and cleaning knowledge graph...");
+  const concepts = result.concepts || [];
+  const categories = result.categories || [];
+  {
+    const STOP = /* @__PURE__ */ new Set(["and", "the", "for", "with", "from", "that", "this", "into", "when", "while", "using", "their", "your", "each", "how", "why", "what", "between", "through", "about"]);
+    const tokensFrom = (text) => text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4 && !STOP.has(w));
+    for (const c of concepts) {
+      const existing = (c.keywords || []).map((k) => String(k).trim()).filter(Boolean);
+      if (existing.length === 0) {
+        const derived = [.../* @__PURE__ */ new Set([...tokensFrom(c.name), ...tokensFrom(c.description || "")])].slice(0, 5);
+        if (derived.length === 0) {
+          throw new Error("Concept " + c.id + " (" + c.name + ") has no keywords and none could be derived from name/description \u2014 fail-closed");
+        }
+        c.keywords = derived;
+        warnings.push("Concept " + c.id + ": empty keyword set - derived " + derived.join(", ") + " from name/description");
+      } else {
+        c.keywords = existing;
+      }
+    }
+  }
+  const rawPath = result.learning_path;
+  let learningPath = (rawPath || []).map((s) => ({
+    concept_id: String(s.concept_id || ""),
+    order: Number(s.order || 0),
+    depends_on: Array.isArray(s.depends_on) ? s.depends_on.map(String) : [],
+    milestone_name: String(s.milestone_name || "")
+  }));
+  const conceptIds = new Set(concepts.map((c) => c.id));
+  for (const concept of concepts) {
+    for (const prereq of concept.prerequisites || []) {
+      if (!conceptIds.has(prereq)) {
+        warnings.push(`Concept ${concept.id} references non-existent prerequisite ${prereq} \u2014 removed`);
+        concept.prerequisites = (concept.prerequisites || []).filter((p) => p !== prereq);
+      }
+    }
+  }
+  if (options.knowledgeTreePath) {
+    const catalog = loadKnowledgeTreeCatalog(options.knowledgeTreePath);
+    log("STEP_2_5", "Knowledge tree loaded: " + catalog.concepts.length + " concepts from " + catalog.path.split("/").pop());
+    const std = await standardizeConcepts({
+      client,
+      concepts: concepts.map((c) => ({
+        id: c.id,
+        name: c.name,
+        description: c.description || "",
+        keywords: c.keywords || []
+      })),
+      catalog,
+      techStack,
+      proposalsPath: options.proposalsPath,
+      onProgress: log
+    });
+    warnings.push(...std.warnings);
+    const codeByStd = new Map(std.decisions.map((d) => [d.id, d]));
+    for (const c of concepts) {
+      const d = codeByStd.get(c.id);
+      if (!d) throw new Error("Concept " + c.id + " missing standardization decision \u2014 fail-closed");
+      if (d.decision === "standardized") {
+        c.standardization = "standardized";
+        c.tree_code = d.tree_code;
+        c.code = d.tree_code;
+        const tc = catalog.concepts.find((x) => x.code === d.tree_code);
+        if (tc) {
+          for (const k of d.adopted_keywords || []) {
+            if (!(c.keywords || []).some((x) => x.toLowerCase() === k.toLowerCase())) {
+              c.keywords = [...c.keywords || [], k];
+            }
+          }
+          c.tree_prerequisites = tc.prerequisiteCodes;
+        }
+      } else {
+        c.standardization = "proposed_new";
+        c.code = d.proposed_code;
+      }
+    }
+    const idByTreeCode = new Map(concepts.filter((c) => c.tree_code).map((c) => [c.tree_code, c.id]));
+    for (const c of concepts) {
+      for (const tp of c.tree_prerequisites || []) {
+        const target = idByTreeCode.get(tp);
+        if (target && target !== c.id && !(c.prerequisites || []).includes(target)) {
+          c.prerequisites = [...c.prerequisites || [], target];
+          warnings.push("Prereq seeded from tree: " + c.id + " <- " + tp + " (" + target + ")");
+        }
+      }
+    }
+    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);
+  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);
+    for (let i = 0; i < concepts.length; i++) {
+      const fixedConcept = fixed.find((f) => f.id === concepts[i].id);
+      if (fixedConcept) {
+        concepts[i] = { ...concepts[i], prerequisites: fixedConcept.prerequisites };
+      }
+    }
+    for (const { from, to } of removed) {
+      warnings.push(`Removed prerequisite edge: ${from} \u2192 ${to} (cycle breaker)`);
+    }
+  }
+  log("STEP_4", "Topological sort of concepts...");
+  const sortedIds = topologicalSort(concepts);
+  learningPath = sortedIds.map((id, idx) => {
+    const concept = concepts.find((c) => c.id === id);
+    return {
+      concept_id: id,
+      order: idx + 1,
+      depends_on: concept?.prerequisites || [],
+      milestone_name: ""
+    };
+  });
+  log("STEP_5", "Authoring ULO/CIO/SIO depth layers hierarchically...");
+  {
+    const lo = await authorDepthLayersHierarchically(
+      client,
+      concepts.map((c) => ({ id: c.id, name: c.name, description: c.description, keywords: c.keywords })),
+      techStack || (domain === "software" || domain === "technology" ? "python" : domain || "general"),
+      warnings
+    );
+    const codeByConceptId = assignConceptCodes(concepts.map((c) => ({ id: c.id, name: c.name })));
+    const techTag = techTagFor(techStack || (domain === "software" || domain === "technology" ? "python" : domain || "general"));
+    for (const concept of concepts) {
+      concept.ulo = lo.uloByConcept[concept.id] || concept.ulo || "";
+      concept.cio = lo.cioByConcept[concept.id] || concept.cio || "";
+      if (lo.sioByConcept[concept.id] && lo.sioByConcept[concept.id].length > 0) {
+        concept.sio = lo.sioByConcept[concept.id];
+      }
+      concept.code = concept.code || codeByConceptId[concept.id];
+      concept.ulo_code = concept.ulo ? uloCode(concept.code) : concept.ulo_code;
+      concept.cio_code = concept.cio ? cioCode(concept.code, 1, cioActionSlug(concept.cio)) : concept.cio_code;
+      concept.sio_codes = concept.sio.length > 0 ? concept.sio.map((_, i) => sioCode(techTag, concept.code, i + 1)) : concept.sio_codes;
+    }
+    log("STEP_5", "Depth layers authored: " + concepts.length + " concepts, audit " + lo.audits.filter((a) => a.passed).length + "/" + concepts.length + " passed");
+  }
+  for (const step of learningPath) {
+    if (!conceptIds.has(step.concept_id)) {
+      warnings.push(`Learning path references non-existent concept ${step.concept_id}`);
+    }
+  }
+  log("STEP_2", `Validated ${concepts.length} concepts, ${categories.length} categories, ${learningPath.length} learning path steps`);
+  return {
+    knowledgeGraph: {
+      schema_version: 1,
+      type: "knowledge_graph",
+      subject: result.subject,
+      concepts,
+      categories,
+      learning_path: learningPath
+    },
+    warnings
+  };
+}
+
+// src/graph/hybridGraphPipeline.ts
+async function generateHybridGraph(options) {
+  const { projectGraph, knowledgeGraph, llmConfig, onProgress } = options;
+  const warnings = [];
+  const log = (step, msg) => {
+    console.log("[HG-" + step + "] " + msg);
+    onProgress?.(step, msg);
+  };
+  const features = projectGraph.features || [];
+  const concepts = knowledgeGraph.concepts || [];
+  if (features.length === 0 || concepts.length === 0) {
+    warnings.push("No features or concepts to link");
+    return {
+      hybridGraph: {
+        schema_version: 1,
+        type: "hybrid_graph",
+        project_graph: projectGraph,
+        knowledge_graph: knowledgeGraph,
+        links: [],
+        phases: [],
+        description: "",
+        total_project_minutes: 0,
+        total_concept_minutes: 0,
+        estimated_total_minutes: 0
+      },
+      warnings
+    };
+  }
+  const client = createLlmClient(llmConfig);
+  const featuresList = features.map(
+    (f) => "- " + f.id + ": " + f.name + " - " + (f.description || "") + " (keywords: " + (f.steps || []).flatMap((s) => s.keywords || []).slice(0, 5).join(", ") + ")"
+  ).join("\n");
+  const conceptsList = concepts.map(
+    (c) => "- " + c.id + ": " + c.name + " - ULO: " + (c.ulo || "").slice(0, 100) + " (prerequisites: " + (c.prerequisites || []).join(", ") + ")"
+  ).join("\n");
+  const systemPrompt = "You are a curriculum architect. Link project features to knowledge concepts.\nFor each feature, determine which concepts it requires or demonstrates.\n\nRULES:\n1. Each link must have a relationship type: requires | demonstrates | applies | extends\n2. depth indicates how deeply the feature needs the concept:\n   - ulo: feature only needs WHAT+WHY understanding\n   - cio: feature needs HOW understanding\n   - sio: feature needs specific implementation knowledge\n3. estimated_prereq_minutes: how many minutes of concept learning before this feature\n4. Not every feature needs every concept - only create meaningful links\n5. Return JSON object with a links array";
+  const userPrompt = "FEATURES:\n" + featuresList + "\n\nCONCEPTS:\n" + conceptsList + "\n\nCreate links between features and concepts. Return JSON.\n";
+  const result = await llmChatJson(client, systemPrompt, userPrompt, {
+    temperature: 0.1,
+    maxTokens: 16384
+  });
+  const rawLinks = result.links || [];
+  const featureIds = new Set(features.map((f) => f.id));
+  const conceptIds = new Set(concepts.map((c) => c.id));
+  const validLinks = [];
+  for (const link of rawLinks) {
+    const fid = String(link.feature_id || "");
+    const cid = String(link.concept_id || "");
+    if (!featureIds.has(fid)) {
+      warnings.push("Link references non-existent feature " + fid);
+      continue;
+    }
+    if (!conceptIds.has(cid)) {
+      warnings.push("Link references non-existent concept " + cid);
+      continue;
+    }
+    validLinks.push({
+      feature_id: fid,
+      concept_id: cid,
+      relationship: link.relationship || "requires",
+      depth: link.depth || "cio",
+      description: String(link.description || ""),
+      estimated_prereq_minutes: Number(link.estimated_prereq_minutes) || 0,
+      phase_id: ""
+    });
+  }
+  log("STEP_1", "Generated " + validLinks.length + " feature-concept links");
+  const phases = await decomposePhases({
+    features,
+    concepts,
+    links: validLinks,
+    client,
+    log,
+    warnings
+  });
+  const phaseByFeature = /* @__PURE__ */ new Map();
+  for (const ph of phases) {
+    for (const fid of ph.feature_ids) phaseByFeature.set(fid, ph.id);
+  }
+  for (const link of validLinks) link.phase_id = phaseByFeature.get(link.feature_id) || "";
+  log("STEP_3", "Calculating totals...");
+  const totalProjectMinutes = features.reduce((sum, f) => {
+    const featureMinutes = (f.steps || []).reduce((s, step) => s + (step.effort?.estimated_minutes || 15), 0);
+    return sum + featureMinutes;
+  }, 0);
+  const totalConceptMinutes = concepts.reduce((sum, c) => sum + (c.estimated_minutes || 30), 0);
+  const prereqMinutesByConcept = /* @__PURE__ */ new Map();
+  for (const link of validLinks) {
+    const mins = link.estimated_prereq_minutes || 0;
+    if (mins > 0) {
+      const existing = prereqMinutesByConcept.get(link.concept_id) || 0;
+      prereqMinutesByConcept.set(link.concept_id, Math.max(existing, mins));
+    }
+  }
+  const totalPrereqMinutes = Array.from(prereqMinutesByConcept.values()).reduce((a, b) => a + b, 0);
+  return {
+    hybridGraph: {
+      schema_version: 1,
+      type: "hybrid_graph",
+      project_graph: projectGraph,
+      knowledge_graph: knowledgeGraph,
+      links: validLinks,
+      phases,
+      description: "Progressive completion path: " + phases.length + " phases, " + features.length + " features, " + concepts.length + " concepts",
+      total_project_minutes: totalProjectMinutes,
+      total_concept_minutes: totalConceptMinutes,
+      estimated_total_minutes: totalProjectMinutes + totalPrereqMinutes
+    },
+    warnings
+  };
+}
+function auditPhasePlan(plan, features, concepts, links, warnings, log) {
+  const knownFeatureIds = new Set(features.map((f) => f.id));
+  const knownConceptIds = new Set(concepts.map((c) => c.id));
+  const prereqOf = /* @__PURE__ */ new Map();
+  for (const c of concepts) prereqOf.set(c.id, (c.prerequisites || []).filter((p) => knownConceptIds.has(p)));
+  const phases = [];
+  const featurePhase = /* @__PURE__ */ new Map();
+  const newIntroPhase = /* @__PURE__ */ new Map();
+  const errors = [];
+  plan.forEach((rp, idx) => {
+    const id = String(rp.id || "PH" + (idx + 1));
+    const order = idx + 1;
+    const name = String(rp.name || "Phase " + order).slice(0, 80);
+    const productCompletion = String(rp.product_completion || "").trim();
+    const rawFeatureIds = Array.isArray(rp.feature_ids) ? rp.feature_ids.map(String) : [];
+    const rawIntros = Array.isArray(rp.introduces) ? rp.introduces : [];
+    if (!productCompletion) {
+      errors.push("Phase " + id + ": product_completion is empty - every phase must describe the product completion level");
+    }
+    const featureIdsForPhase = [];
+    for (const fid of rawFeatureIds) {
+      if (!knownFeatureIds.has(fid)) {
+        errors.push("Phase " + id + ": unknown feature " + fid);
+        continue;
+      }
+      if (featurePhase.has(fid)) {
+        errors.push("Feature " + fid + " assigned to both " + featurePhase.get(fid) + " and " + id + " - each feature must belong to exactly one phase");
+        continue;
+      }
+      featurePhase.set(fid, id);
+      featureIdsForPhase.push(fid);
+    }
+    const introductions = [];
+    for (const ri of rawIntros) {
+      const cid = String(ri.concept_id || "");
+      if (!knownConceptIds.has(cid)) {
+        errors.push("Phase " + id + ": introduces unknown concept " + cid);
+        continue;
+      }
+      const aspect = String(ri.aspect || "new") === "advanced" ? "advanced" : "new";
+      if (aspect === "advanced") {
+        const first = newIntroPhase.get(cid);
+        if (first === void 0) {
+          errors.push("Phase " + id + ": advanced introduction of " + cid + " before any new introduction - revisit requires prior introduction");
+          continue;
+        }
+        if (first >= order) {
+          errors.push("Phase " + id + ": advanced introduction of " + cid + " must come after its new introduction in phase " + first);
+          continue;
+        }
+      } else if (newIntroPhase.has(cid)) {
+        errors.push("Phase " + id + ": duplicate new introduction of " + cid + " (already introduced in phase " + newIntroPhase.get(cid) + ")");
+        continue;
+      } else {
+        newIntroPhase.set(cid, order);
+      }
+      for (const pre of prereqOf.get(cid) || []) {
+        if (!newIntroPhase.has(pre)) {
+          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced - violates the prerequisite chain");
+        }
+      }
+      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
+    }
+    phases.push({
+      id,
+      order,
+      name,
+      product_completion: productCompletion,
+      feature_ids: featureIdsForPhase,
+      introduces: introductions
+    });
+  });
+  const missing = features.map((f) => f.id).filter((fid) => !featurePhase.has(fid));
+  if (missing.length > 0) {
+    errors.push("Features not assigned to any phase: " + missing.join(", "));
+  }
+  const firstConsumerPhase = /* @__PURE__ */ new Map();
+  const phaseOrderByFeature = /* @__PURE__ */ new Map();
+  for (const ph of phases) for (const fid of ph.feature_ids) phaseOrderByFeature.set(fid, ph.order);
+  for (const l of links) {
+    const po = phaseOrderByFeature.get(l.feature_id);
+    if (po === void 0) continue;
+    const cur = firstConsumerPhase.get(l.concept_id);
+    if (cur === void 0 || po < cur) firstConsumerPhase.set(l.concept_id, po);
+  }
+  for (const [cid, consumerOrder] of firstConsumerPhase) {
+    const intro = newIntroPhase.get(cid);
+    if (intro === void 0) {
+      errors.push("Concept " + cid + " is consumed from phase " + consumerOrder + " but never introduced in any phase");
+    } else if (intro > consumerOrder) {
+      errors.push("Concept " + cid + " introduced in phase " + intro + " but first consumed in phase " + consumerOrder + " - introduction must come no later than first consumption");
+    }
+  }
+  return { phases, errors };
+}
+async function decomposePhases(args) {
+  const { features, concepts, links, client, log, warnings } = args;
+  const featureList = features.map(
+    (f) => "- " + f.id + ": " + f.name + " - " + (f.description || "").slice(0, 120)
+  ).join("\n");
+  const conceptList = concepts.map(
+    (c) => "- " + c.id + ": " + c.name + " (prerequisites: " + ((c.prerequisites || []).join(", ") || "none") + ")"
+  ).join("\n");
+  const linkList = links.map(
+    (l) => "- " + l.feature_id + " -> " + l.concept_id + " (" + l.depth + ")"
+  ).join("\n") || "(none)";
+  const systemPrompt = "You decompose a software project build into PROGRESSIVE COMPLETION PHASES for learning purposes.\n\nA phase is NOT a feature and NOT a milestone list: it is a cross-feature slice of the\nproduct whose completion yields a DEMONSTRABLY more complete product. Build up gradually:\nthe product grows feature by feature across phases, and each phase adds its features to\nwhat previous phases already built.\n\nRULES:\n1. Every feature must be assigned to EXACTLY ONE phase (no feature reused, none skipped).\n2. Phases are ordered; later phases depend on earlier ones and yield a more complete product.\n3. product_completion describes concretely what the product can DO once the phase is done.\n4. introduces lists which concepts the phase must teach BEFORE its feature work starts:\n   - aspect new: first time the concept appears in the course\n   - aspect advanced: a concept introduced in an EARLIER phase, revisited here at a\n     higher depth (an advanced aspect of the same concept, e.g. validation rules on top\n     of basic data modeling). Use the note field to say which aspect.\n5. A concept MUST be introduced (new) no later than the first phase that consumes it.\n6. A concept must not be introduced before its own prerequisites are introduced.\n7. Typically 3-6 phases for a small project; keep phases balanced.\n8. Phase 1 usually covers project setup/foundation features plus the first minimal slice.\n9. Return JSON only.";
+  const baseUserPrompt = "FEATURES:\n" + featureList + "\n\nCONCEPTS:\n" + conceptList + "\n\nFEATURE-CONCEPT LINKS:\n" + linkList + "\n\nReturn JSON with a phases array. Each phase: { id: PH1, name, product_completion, feature_ids: [F0, F1], introduces: [{ concept_id: C1, aspect: new or advanced, note }] }.\n";
+  const MAX_DECOMPOSE_ATTEMPTS = 3;
+  let auditErrors = [];
+  let phases = [];
+  let rawPhases = [];
+  for (let attempt = 1; attempt <= MAX_DECOMPOSE_ATTEMPTS; attempt++) {
+    const userPrompt = attempt === 1 ? baseUserPrompt : baseUserPrompt + "\nYOUR PREVIOUS PLAN VIOLATED THESE CONTRACT RULES (fix ALL of them):\n" + auditErrors.map((e) => "- " + e).join("\n") + "\nReturn a corrected full phases array.\n";
+    const result = await llmChatJson(client, systemPrompt, userPrompt, {
+      temperature: 0.1,
+      maxTokens: 16384
+    });
+    rawPhases = result.phases || [];
+    if (rawPhases.length === 0) {
+      if (attempt === MAX_DECOMPOSE_ATTEMPTS) {
+        throw new Error("Phase decomposition returned zero phases - fail-closed abort");
+      }
+      auditErrors = ["Returned zero phases"];
+      continue;
+    }
+    ({ phases, errors: auditErrors } = auditPhasePlan(rawPhases, features, concepts, links));
+    if (auditErrors.length === 0) break;
+    if (attempt < MAX_DECOMPOSE_ATTEMPTS) {
+      log("STEP_2", "Contract violations (" + auditErrors.length + ") - repairing (attempt " + (attempt + 1) + "/" + MAX_DECOMPOSE_ATTEMPTS + ")");
+    }
+  }
+  if (auditErrors.length > 0) {
+    throw new Error(
+      "Phase decomposition violated the progressive-completion contract (" + auditErrors.length + " issue(s)):\n" + auditErrors.map((e) => "  - " + e).join("\n") + "\nRe-run the pipeline - a phase model that cannot be trusted is worse than no output."
+    );
+  }
+  if (phases.length === 1 && features.length > 2) {
+    warnings.push("Only one phase for " + features.length + " features - progressive decomposition likely too coarse");
+  }
+  log("STEP_2", "Decomposed into " + phases.length + " phases: " + phases.map((p) => p.id + "(" + p.feature_ids.length + "F/" + p.introduces.length + "K)").join(", "));
+  return phases;
+}
+
+exports.CIO_CODE_RE = CIO_CODE_RE;
+exports.CONCEPT_CODE_RE = CONCEPT_CODE_RE;
+exports.LEARNER_CLAUSE = LEARNER_CLAUSE;
+exports.SIO_CODE_RE = SIO_CODE_RE;
+exports.ULO_CODE_RE = ULO_CODE_RE;
+exports.assignConceptCodes = assignConceptCodes;
+exports.auditDepthLayers = auditDepthLayers;
+exports.cioActionSlug = cioActionSlug;
+exports.cioCode = cioCode;
+exports.conceptCodeFromName = conceptCodeFromName;
+exports.escalateAndMapConcepts = escalateAndMapConcepts;
+exports.extractFeatureSteps = extractFeatureSteps;
+exports.extractFeatureStepsBatched = extractFeatureStepsBatched;
+exports.extractProjectOverview = extractProjectOverview;
+exports.extractScaffold = extractScaffold;
+exports.generateHybridGraph = generateHybridGraph;
+exports.generateKnowledgeGraph = generateKnowledgeGraph;
+exports.sioCode = sioCode;
+exports.standardStatement = standardStatement;
+exports.techTagFor = techTagFor;
+exports.uloCode = uloCode;
+exports.verifyProjectGraph = verifyProjectGraph;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map