@thanh01.pmt/domain-kit 0.4.0 → 0.6.0

package/dist/graph/index.cjs

@@ -37,9 +37,10 @@ function resolveProviderChain(config) {
   return chain;
 }
 var MIN_REQUEST_INTERVAL_MS = 2500;
+var requestIntervalMs = Number(process.env.LLM_MIN_REQUEST_INTERVAL_MS || MIN_REQUEST_INTERVAL_MS);
 var lastRequestAt = 0;
 async function pacedDelay() {
-  const wait = lastRequestAt + MIN_REQUEST_INTERVAL_MS - Date.now();
+  const wait = lastRequestAt + requestIntervalMs - Date.now();
   if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
   lastRequestAt = Date.now();
 }
@@ -54,6 +55,10 @@ function createLlmClient(config) {
   primary.apiKey;
   primary.baseUrl;
   const model = primary.model;
+  if (config?.minRequestIntervalMs !== void 0) {
+    requestIntervalMs = Math.max(0, config.minRequestIntervalMs);
+  }
+  const callLog = [];
   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);
@@ -68,6 +73,7 @@ function createLlmClient(config) {
         await new Promise((resolve) => setTimeout(resolve, 2e4));
       }
       for (const provider of chain) {
+        const recIdx = callLog.push({ provider: provider.label, model: provider.model, ok: false }) - 1;
         try {
           const headers = {
             "Content-Type": "application/json",
@@ -128,6 +134,7 @@ function createLlmClient(config) {
               const retryData = await retry.json();
               const retryContent2 = retryData.choices?.[0]?.message?.content || "";
               if (!retryContent2.trim()) throw err;
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
               return {
                 content: retryContent2,
                 model: retryData.model || provider.model,
@@ -156,6 +163,7 @@ function createLlmClient(config) {
               if (!retry.ok) throw err;
               const retryData = await retry.json();
               const retryContent = retryData.choices?.[0]?.message?.content || "";
+              callLog[recIdx] = { ...callLog[recIdx], ok: true };
               return {
                 content: retryContent,
                 model: retryData.model || provider.model,
@@ -186,6 +194,7 @@ function createLlmClient(config) {
           };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
+          callLog[recIdx] = { ...callLog[recIdx], ok: false, error: msg.slice(0, 200) };
           attempts.push(`${provider.label}: ${msg}`);
           lastError = err instanceof LlmClientError ? err : new LlmClientError(`[${provider.label}] ${msg}`);
         }
@@ -195,7 +204,7 @@ function createLlmClient(config) {
     }
     throw lastError ?? new LlmClientError("All LLM providers failed after " + MAX_CHAIN_ROUNDS + " rounds.");
   }
-  return { chat, model };
+  return { chat, model, callLog };
 }
 function parseJsonFromLlm(text) {
   let cleaned = text.trim();
@@ -259,8 +268,8 @@ async function llmChatJson(client, systemPrompt, userPrompt, options) {
 
 // src/graph/scaffoldExtractor.ts
 async function extractScaffold(options) {
-  const { goal, techStack, fileList, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, fileList, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? 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}
@@ -345,8 +354,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractProjectOverview(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, astKeywords, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? 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 = "";
@@ -415,8 +424,8 @@ ${content}`);
   return blocks.join("\n\n");
 }
 async function extractFeatureSteps(options) {
-  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig } = options;
-  const client = createLlmClient(llmConfig);
+  const { goal, techStack, sdkApiIndex, fileContentsMap, feature, llmConfig, sharedClient } = options;
+  const client = sharedClient ?? 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";
@@ -483,8 +492,8 @@ Split this feature into 2-6 action steps. Return JSON:
     concept_codes: []
   }));
 }
-async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig) {
-  const client = createLlmClient(llmConfig);
+async function extractFeatureStepsBatched(goal, techStack, sdkApiIndex, fileContentsMap, featuresMeta, llmConfig, sharedClient) {
+  const client = sharedClient ?? 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(
@@ -751,7 +760,7 @@ function inferDepthFromContext(keyword, fileContentsMap) {
   return { depth: "sio", rationale: `Default: treating '${keyword}' as SIO (implementation-level)` };
 }
 async function escalateAndMapConcepts(options) {
-  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig } = options;
+  const { projectGraph, fileContentsMap, availableConcepts, conceptMapOverride, llmConfig, sharedClient } = options;
   const features = projectGraph.features || [];
   const allTerms = /* @__PURE__ */ new Set();
   for (const feature of features) {
@@ -767,7 +776,7 @@ async function escalateAndMapConcepts(options) {
     llmResults = conceptMapOverride;
   } else {
     try {
-      const client = createLlmClient(llmConfig);
+      const client = sharedClient ?? createLlmClient(llmConfig);
       const conceptBank = (availableConcepts || []).sort().join(", ") || "(empty)";
       const termEntries = termList.map((term) => {
         const snippets = extractTermSnippets(term, fileContentsMap);
@@ -820,13 +829,16 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
       const cName = info.concept_name || kw;
       let depth = "sio";
       let depthRationale = "Default: SIO";
+      let depthSource = "override";
       if (info.depth && ["ulo", "cio", "sio"].includes(info.depth)) {
         depth = info.depth;
         depthRationale = `LLM classified as ${depth}`;
+        depthSource = "llm";
       } else {
         const inferred = inferDepthFromContext(kw, fileContentsMap);
         depth = inferred.depth;
         depthRationale = inferred.rationale;
+        depthSource = "heuristic";
       }
       const kwKey = `${cCode}::${kw}`;
       if (seen.has(kwKey)) continue;
@@ -844,6 +856,7 @@ Return JSON: {"results": {"<keyword>": {"concept_code": "...", "concept_name": "
         keyword: kw,
         depth,
         depth_rationale: depthRationale,
+        depth_source: depthSource,
         evidence_files: evidenceFiles
       });
     }
@@ -968,6 +981,13 @@ 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/utils/diacritics.ts
+var COMBINING_MARKS = /[\u0300-\u036f]/g;
+var D_WITH_STROKE = /đ/gi;
+function stripDiacritics(s) {
+  return s.normalize("NFD").replace(COMBINING_MARKS, "").replace(D_WITH_STROKE, "d").toLowerCase();
+}
+
 // src/parsers/syllabusParser.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "and",
@@ -1730,7 +1750,7 @@ function loadKnowledgeTreeCatalog(tsvPath) {
 }
 function tokens(s) {
   return new Set(
-    s.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
+    stripDiacritics(s).replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length >= 4)
   );
 }
 function filterBySelection(catalog, selectedCategories, selectedTopics, analysisConcepts, maxConcepts = 120) {
@@ -1904,6 +1924,15 @@ async function standardizeConcepts(opts) {
 }
 
 // src/graph/knowledgeGraphPipeline.ts
+var MIN_CALIBRATION_MINUTES = 15;
+var MAX_CALIBRATION_MINUTES = 60;
+var DEFAULT_CONCEPT_MINUTES = 30;
+var MIN_CALIBRATION_DIVERGENCE = 0.5;
+function calibrateConceptMinutes(sioCount, problemTypeCount, prereqCount, hasHighBloom) {
+  const ratio = (value, cap) => Math.min(1, Math.max(0, value) / cap);
+  const score = 0.3 * ratio(sioCount, 4) + 0.25 * ratio(problemTypeCount, 4) + 0.2 * ratio(prereqCount, 4) + 0.25 * (hasHighBloom ? 1 : 0);
+  return Math.round(MIN_CALIBRATION_MINUTES + score * (MAX_CALIBRATION_MINUTES - MIN_CALIBRATION_MINUTES));
+}
 function topologicalSort(concepts) {
   const inDegree = /* @__PURE__ */ new Map();
   const adjacency = /* @__PURE__ */ new Map();
@@ -1963,7 +1992,42 @@ async function generateKnowledgeGraph(options) {
   const structuredTopicsGuide = parsedSyllabus && parsedSyllabus.allTopics.length > 0 ? `
 STRUCTURED SYLLABUS TOPICS (Every topic MUST map to at least one concept to ensure 100% syllabus coverage):
 ` + parsedSyllabus.allTopics.map((t) => `- [${t.unitTitle}] ${t.id}: ${t.title} (Keywords: ${t.keywords.join(", ")})`).join("\n") + "\n" : "";
-  const systemPrompt = "You are an expert curriculum designer. Decompose the given subject into a structured knowledge graph with concepts, prerequisites, and problem types.\n\nCRITICAL RULES:\n1. Each concept MUST have the three depth layers, authored against this CONTRACT:\n   - ulo (WHAT + WHY): bound to the CONCEPT's intrinsic NATURE. It explains what the\n     concept is and why it exists \u2014 the problem it solves in principle. It must be\n     TECHNOLOGY-AGNOSTIC: never name a concrete library, API, function, file format,\n     tool or language feature. Typical assessment level: Remember / Understand.\n   - cio (HOW): the MECHANISM \u2014 how the concept works and solves that problem, step\n     by step. Still bound to the concept's nature: more concrete than the ULO, but\n     NOT tied to one specific technology (no concrete API names). CIO capability is\n     assessed INDIRECTLY, through completing contextual work, not in isolation.\n   - sio (IMPLEMENTATION): an array of 2-4 items. EVERY item MUST reference concrete\n     KEYWORDS/technologies (a real API, function, module, file, or named pattern) and\n     describe a completable, context-specific implementation task. Application,\n     Analysis and Creation skills are assessed INDIRECTLY through completing these\n     items. There is NO fixed Bloom ceiling for a layer \u2014 but concreteness MUST\n     strictly increase: SIO more technology-bound than CIO, CIO more concrete than ULO.\n   - prerequisites: concept IDs that must be learned first (MUST NOT create cycles)\n   - problem_types: 2-4 problem types with bloom_level and difficulty. Remember and\n     Understand problem types test the ULO/CIO directly; Apply-and-above types are\n     proxies for SIO completion in context.\n   - techniques: methods, formulas, tools\n2. Prerequisite chains MUST be acyclic (no concept can depend on itself or create a loop)\n3. Concepts should be ordered by prerequisite dependency (topological sort)\n4. Problem types should range from Remember to Apply (not all at same level)\n5. Group concepts into categories (chapters/sections)\n6. ALL text in ENGLISH (even if input is Vietnamese)\n7. NEVER invent concepts not present in the syllabus\n8. Return JSON matching the KnowledgeGraphSchema";
+  const systemPrompt = `You are an expert curriculum designer. Decompose the given subject into a structured knowledge graph with concepts, prerequisites, and problem types.
+
+CRITICAL RULES:
+1. Each concept MUST have the three depth layers, authored against this CONTRACT:
+   - ulo (WHAT + WHY): bound to the CONCEPT's intrinsic NATURE. It explains what the
+     concept is and why it exists \u2014 the problem it solves in principle. It must be
+     TECHNOLOGY-AGNOSTIC: never name a concrete library, API, function, file format,
+     tool or language feature. Typical assessment level: Remember / Understand.
+   - cio (HOW): the MECHANISM \u2014 how the concept works and solves that problem, step
+     by step. Still bound to the concept's nature: more concrete than the ULO, but
+     NOT tied to one specific technology (no concrete API names). CIO capability is
+     assessed INDIRECTLY, through completing contextual work, not in isolation.
+   - sio (IMPLEMENTATION): an array of 2-4 items. EVERY item MUST reference concrete
+     KEYWORDS/technologies (a real API, function, module, file, or named pattern) and
+     describe a completable, context-specific implementation task. Application,
+     Analysis and Creation skills are assessed INDIRECTLY through completing these
+     items. There is NO fixed Bloom ceiling for a layer \u2014 but concreteness MUST
+     strictly increase: SIO more technology-bound than CIO, CIO more concrete than ULO.
+   - prerequisites: concept IDs that must be learned first (MUST NOT create cycles)
+   - problem_types: 2-4 problem types with bloom_level and difficulty. Remember and
+     Understand problem types test the ULO/CIO directly; Apply-and-above types are
+     proxies for SIO completion in context.
+   - techniques: methods, formulas, tools
+2. Prerequisite chains MUST be acyclic (no concept can depend on itself or create a loop)
+3. Concepts should be ordered by prerequisite dependency (topological sort)
+4. Problem types should range from Remember to Apply (not all at same level)
+5. Group concepts into categories (chapters/sections)
+6. ALL text in ENGLISH (even if input is Vietnamese)
+7. NEVER invent concepts not present in the syllabus
+8. KEYWORDS: Each concept MUST include 5-10 domain-specific keywords that:
+   - Are concrete terms a student encounters when studying THIS concept
+   - Include at least 2 technology-specific terms (APIs, functions, types, tools)
+   - Are DISTINCT from keywords of other concepts (minimal overlap)
+   - NEVER generic English words (e.g. "view", "data", "code" are TOO generic)
+   - Example for "SwiftUI Layout": ["VStack", "HStack", "ZStack", ".padding()", ".frame()", "alignment", "Spacer", "LazyVGrid"]
+9. Return JSON matching the KnowledgeGraphSchema`;
   const userPrompt = `Subject: ${subject}
 ${description ? `Description: ${description}` : ""}
 ${structuredTopicsGuide}${truncatedSyllabus ? `Syllabus:
@@ -1984,8 +2048,9 @@ Return JSON:
     {
       "id": "C1",
       "name": "Concept name",
-      "description": "Brief description",
+      "description": "2-3 sentence description: what this concept covers, why a learner encounters it, and what mastering it enables. Must be specific enough that a student reading only this description understands the concept's scope.",
       "category": "category_id",
+      "keywords": ["specific_term_1", "concrete_api_2", "method_call_3", "tool_or_type_4", "syntax_keyword_5", "concept_term_6"],
       "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"],
@@ -2026,18 +2091,23 @@ Return JSON:
   log("STEP_2", "Validating and cleaning knowledge graph...");
   const concepts = result.concepts || [];
   const categories = result.categories || [];
+  for (const c of concepts) {
+    if ((c.description || "").length < 50) {
+      warnings.push("Concept " + c.id + ": description too short (" + (c.description || "").length + " chars) \u2014 may produce shallow KX narratives");
+    }
+  }
   {
     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));
+    const tokensFrom = (text) => stripDiacritics(text).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);
+        const derived = [.../* @__PURE__ */ new Set([...tokensFrom(c.name), ...tokensFrom(c.description || "")])].slice(0, 8);
         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");
+        warnings.push("Concept " + c.id + ": empty keyword set - derived " + derived.join(", ") + " from name/description (WARNING: LLM returned no keywords)");
       } else {
         c.keywords = existing;
       }
@@ -2162,6 +2232,49 @@ Return JSON:
     }
     log("STEP_5", "Depth layers authored: " + concepts.length + " concepts, audit " + lo.audits.filter((a) => a.passed).length + "/" + concepts.length + " passed");
   }
+  {
+    for (const concept of concepts) {
+      const sioText = (concept.sio || []).join(" ");
+      const techTokens = [];
+      let m;
+      const techTokenRe = /`([^`]+)`/g;
+      while ((m = techTokenRe.exec(sioText)) !== null) {
+        if (m[1].length >= 3 && m[1].length <= 40) techTokens.push(m[1]);
+      }
+      const annotationRe = /(?:^|[\s(])(@[A-Za-z]\w*)/g;
+      while ((m = annotationRe.exec(sioText)) !== null) techTokens.push(m[1]);
+      const dotRe = /\b\w+\.\w+\(/g;
+      while ((m = dotRe.exec(sioText)) !== null) techTokens.push(m[0].replace("(", ""));
+      const modifierRe = /(?:^|[\s(])(\.[a-z]\w*)\b/g;
+      while ((m = modifierRe.exec(sioText)) !== null) techTokens.push(m[1]);
+      const camelRe = /\b[a-z]+[A-Z][A-Za-z]+\b/g;
+      while ((m = camelRe.exec(sioText)) !== null) techTokens.push(m[0]);
+      const existing = new Set((concept.keywords || []).map((k) => k.toLowerCase()));
+      const newTokens = [...new Set(techTokens)].filter((t) => !existing.has(t.toLowerCase())).slice(0, 8);
+      if (newTokens.length > 0) {
+        concept.keywords = [...concept.keywords || [], ...newTokens];
+        warnings.push("Concept " + concept.id + ": enriched keywords with " + newTokens.length + " SIO-derived tokens");
+      }
+    }
+    log("STEP_5b", "SIO-keyword enrichment complete");
+  }
+  {
+    for (const concept of concepts) {
+      const sioCount = (concept.sio || []).length;
+      const ptCount = (concept.problem_types || []).length;
+      const prereqCount = (concept.prerequisites || []).length;
+      const hasHighBloom = (concept.problem_types || []).some(
+        (pt) => ["Analyze", "Evaluate", "Create"].includes(pt.bloom_level || "")
+      );
+      const calibrated = calibrateConceptMinutes(sioCount, ptCount, prereqCount, hasHighBloom);
+      const llmEstimate = concept.estimated_minutes || DEFAULT_CONCEPT_MINUTES;
+      if (Math.abs(calibrated - llmEstimate) / llmEstimate > MIN_CALIBRATION_DIVERGENCE) {
+        concept.estimated_minutes = calibrated;
+        warnings.push("Concept " + concept.id + ": minutes calibrated " + llmEstimate + "m \u2192 " + calibrated + "m");
+      }
+    }
+    log("STEP_5c", "Minute calibration complete");
+  }
   for (const step of learningPath) {
     if (!conceptIds.has(step.concept_id)) {
       warnings.push(`Learning path references non-existent concept ${step.concept_id}`);
@@ -2182,7 +2295,8 @@ Return JSON:
   return {
     knowledgeGraph: verifiedGraph,
     warnings,
-    verificationReport: report
+    verificationReport: report,
+    provenance: client.callLog
   };
 }
 
@@ -2209,9 +2323,10 @@ async function generateHybridGraph(options) {
         description: "",
         total_project_minutes: 0,
         total_concept_minutes: 0,
-        estimated_total_minutes: 0
+        linked_prereq_minutes: 0
       },
-      warnings
+      warnings,
+      provenance: []
     };
   }
   const client = createLlmClient(llmConfig);
@@ -2292,9 +2407,14 @@ async function generateHybridGraph(options) {
       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
+      // HG-1 (2026-10-05): renamed from estimated_total_minutes. It counts only
+      // concepts that HAVE a feature link (max per concept, not summed), so it
+      // is NOT the course total — see HybridGraphSchema.linked_prereq_minutes.
+      // The phase planner below commits to totalProjectMinutes + totalConceptMinutes.
+      linked_prereq_minutes: totalProjectMinutes + totalPrereqMinutes
     },
-    warnings
+    warnings,
+    provenance: client.callLog
   };
 }
 function auditPhasePlan(plan, features, concepts, links, warnings, log) {
@@ -2370,12 +2490,20 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
       } else {
         newIntroPhase.set(cid, order);
       }
+      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
+    }
+    for (const intro of introductions) {
+      const cid = intro.concept_id;
+      if (intro.aspect === "advanced") continue;
+      const introOrder = newIntroPhase.get(cid);
+      if (introOrder === void 0 || introOrder !== order) continue;
       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");
+        const previewOrder = previewPhase.get(pre);
+        const covered = newIntroPhase.has(pre) || previewOrder !== void 0 && previewOrder < order;
+        if (!covered) {
+          errors.push("Phase " + id + ": concept " + cid + " introduced before its prerequisite " + pre + " is introduced (or previewed in an earlier phase) - violates the prerequisite chain");
         }
       }
-      introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
     }
     phases.push({
       id,
@@ -2413,6 +2541,9 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
     if (anchor !== void 0 && anchor <= pOrder) {
       errors.push("Concept " + cid + " previewed in phase " + pOrder + " but fully introduced in phase " + anchor + " - preview must precede the anchor introduction");
     }
+    if (anchor === void 0) {
+      errors.push("Concept " + cid + " is previewed in phase " + pOrder + " but never fully introduced (aspect new) in any phase - a preview must have an anchor teach");
+    }
   }
   return { phases, errors };
 }
@@ -2427,8 +2558,12 @@ async function decomposePhases(args) {
   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.\n   - aspect preview: a light awareness pass ("know it exists", ULO depth only, ~5 min)\n     placed in an EARLIER phase when its feature work needs the vocabulary before the\n     full teach. The anchor phase still owns the full new introduction.\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 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.\n   - aspect preview: a light awareness pass ("know it exists", ULO depth only, ~5 min)\n     placed in an EARLIER phase when its feature work needs the vocabulary before the\n     full teach. The anchor phase still owns the full new introduction.\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. MINUTE BALANCE: Each phase should contain approximately 120-240 total minutes of\n   concept + feature work (about 3-5 sessions of 90 minutes each). If a phase\n   would contain < 60 minutes (too thin) or > 400 minutes (too heavy), rebalance.\n9. Phase 1 usually covers project setup/foundation features plus the first minimal slice.\n10. Return JSON only.';
+  const totalFeatureMinutes = features.reduce((s, f) => s + (f.steps || []).reduce((ss, st) => ss + (st.effort?.estimated_minutes || 15), 0), 0);
+  const totalConceptMinutes = concepts.reduce((s, c) => s + (c.estimated_minutes || 30), 0);
+  const totalMinutes = totalFeatureMinutes + totalConceptMinutes;
+  const targetPhaseCount = Math.max(3, Math.round(totalMinutes / 180));
+  const baseUserPrompt = "FEATURES:\n" + featureList + "\n\nCONCEPTS:\n" + conceptList + "\n\nFEATURE-CONCEPT LINKS:\n" + linkList + "\n\nTOTAL MINUTES: ~" + totalMinutes + "m (" + totalFeatureMinutes + "m features + " + totalConceptMinutes + "m concepts)\nTARGET: ~" + targetPhaseCount + " phases of ~180m each\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 = [];