@thanh01.pmt/domain-kit 0.2.1 → 0.3.0

package/dist/graph/index.d.cts

@@ -1,11 +1,11 @@
 import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.cjs';
 import { d as Feature, c as Step } from '../projectGraphSchema-DnD7orZV.cjs';
 import { K as Keyword } from '../keywordExtractor-BxlGRMHC.cjs';
-export { H as Hallucination, i as HybridGraphPipelineOptions, j as HybridGraphPipelineResult, K as KnowledgeGraphPipelineOptions, a as KnowledgeGraphPipelineResult, f as KnowledgeGraphVerificationReport, V as VerifyOptions, e as auditSyllabusCoverage, c as breakPrerequisiteCycles, d as detectPrerequisiteCycles, h as generateHybridGraph, g as generateKnowledgeGraph, b as verifyKnowledgeGraph, v as verifyProjectGraph } from '../hybridGraphPipeline-DmWRKYXf.cjs';
+export { H as Hallucination, i as HybridGraphPipelineOptions, j as HybridGraphPipelineResult, K as KnowledgeGraphPipelineOptions, a as KnowledgeGraphPipelineResult, f as KnowledgeGraphVerificationReport, V as VerifyOptions, e as auditSyllabusCoverage, c as breakPrerequisiteCycles, d as detectPrerequisiteCycles, h as generateHybridGraph, g as generateKnowledgeGraph, b as verifyKnowledgeGraph, v as verifyProjectGraph } from '../hybridGraphPipeline-BhFyh3cm.cjs';
 export { C as ConceptMapping, E as EscalateOptions, e as escalateAndMapConcepts } from '../conceptEscalator-ltRLtPhf.cjs';
 import 'zod';
 import '../cpp-CZUPqJt9.cjs';
-import '../hybridGraphSchema-BCgXicgA.cjs';
+import '../hybridGraphSchema-nrUeSwpU.cjs';
 import '../syllabusParser-MSX1fEzW.cjs';
 
 /**

package/dist/graph/index.d.ts

@@ -1,11 +1,11 @@
 import { L as LlmClientConfig } from '../llmClient-ysPhLjcH.js';
 import { d as Feature, c as Step } from '../projectGraphSchema-DnD7orZV.js';
 import { K as Keyword } from '../keywordExtractor-DU5XRN8-.js';
-export { H as Hallucination, i as HybridGraphPipelineOptions, j as HybridGraphPipelineResult, K as KnowledgeGraphPipelineOptions, a as KnowledgeGraphPipelineResult, f as KnowledgeGraphVerificationReport, V as VerifyOptions, e as auditSyllabusCoverage, c as breakPrerequisiteCycles, d as detectPrerequisiteCycles, h as generateHybridGraph, g as generateKnowledgeGraph, b as verifyKnowledgeGraph, v as verifyProjectGraph } from '../hybridGraphPipeline-DVZYLCAQ.js';
+export { H as Hallucination, i as HybridGraphPipelineOptions, j as HybridGraphPipelineResult, K as KnowledgeGraphPipelineOptions, a as KnowledgeGraphPipelineResult, f as KnowledgeGraphVerificationReport, V as VerifyOptions, e as auditSyllabusCoverage, c as breakPrerequisiteCycles, d as detectPrerequisiteCycles, h as generateHybridGraph, g as generateKnowledgeGraph, b as verifyKnowledgeGraph, v as verifyProjectGraph } from '../hybridGraphPipeline-NZAWAPt_.js';
 export { C as ConceptMapping, E as EscalateOptions, e as escalateAndMapConcepts } from '../conceptEscalator-YfMKIKCZ.js';
 import 'zod';
 import '../cpp-CZUPqJt9.js';
-import '../hybridGraphSchema-BCgXicgA.js';
+import '../hybridGraphSchema-nrUeSwpU.js';
 import '../syllabusParser-MSX1fEzW.js';
 
 /**

package/dist/graph/index.mjs

@@ -1,5 +1,5 @@
 import '../chunk-ZKLT27T4.mjs';
-export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, auditSyllabusCoverage, breakPrerequisiteCycles, cioActionSlug, cioCode, conceptCodeFromName, detectPrerequisiteCycles, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode, verifyKnowledgeGraph, verifyProjectGraph } from '../chunk-CRN6D4HG.mjs';
+export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, auditSyllabusCoverage, breakPrerequisiteCycles, cioActionSlug, cioCode, conceptCodeFromName, detectPrerequisiteCycles, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, sioCode, standardStatement, techTagFor, uloCode, verifyKnowledgeGraph, verifyProjectGraph } from '../chunk-Y7MRFFDJ.mjs';
 import '../chunk-T4Y2DE2W.mjs';
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/{hybridGraphPipeline-DmWRKYXf.d.cts → hybridGraphPipeline-BhFyh3cm.d.cts}

@@ -1,6 +1,6 @@
 import { u as ProjectGraph } from './projectGraphSchema-DnD7orZV.cjs';
 import { L as LlmClientConfig } from './llmClient-ysPhLjcH.cjs';
-import { g as KnowledgeGraph, b as Concept, j as HybridGraph } from './hybridGraphSchema-BCgXicgA.cjs';
+import { g as KnowledgeGraph, b as Concept, j as HybridGraph } from './hybridGraphSchema-nrUeSwpU.cjs';
 import { P as ParsedSyllabus } from './syllabusParser-MSX1fEzW.cjs';
 
 /**

package/dist/{hybridGraphPipeline-DVZYLCAQ.d.ts → hybridGraphPipeline-NZAWAPt_.d.ts}

@@ -1,6 +1,6 @@
 import { u as ProjectGraph } from './projectGraphSchema-DnD7orZV.js';
 import { L as LlmClientConfig } from './llmClient-ysPhLjcH.js';
-import { g as KnowledgeGraph, b as Concept, j as HybridGraph } from './hybridGraphSchema-BCgXicgA.js';
+import { g as KnowledgeGraph, b as Concept, j as HybridGraph } from './hybridGraphSchema-nrUeSwpU.js';
 import { P as ParsedSyllabus } from './syllabusParser-MSX1fEzW.js';
 
 /**

package/dist/{hybridGraphSchema-BCgXicgA.d.ts → hybridGraphSchema-nrUeSwpU.d.cts}

@@ -563,15 +563,15 @@ declare const ProjectConceptLinkSchema: z.ZodObject<{
 }>;
 declare const ConceptIntroductionSchema: z.ZodObject<{
     concept_id: z.ZodString;
-    aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+    aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
     note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     concept_id: string;
-    aspect: "new" | "advanced";
+    aspect: "new" | "advanced" | "preview";
     note: string;
 }, {
     concept_id: string;
-    aspect?: "new" | "advanced" | undefined;
+    aspect?: "new" | "advanced" | "preview" | undefined;
     note?: string | undefined;
 }>;
 declare const DevelopmentPhaseSchema: z.ZodObject<{
@@ -582,15 +582,15 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     feature_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     introduces: z.ZodDefault<z.ZodArray<z.ZodObject<{
         concept_id: z.ZodString;
-        aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+        aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
         note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         concept_id: string;
-        aspect: "new" | "advanced";
+        aspect: "new" | "advanced" | "preview";
         note: string;
     }, {
         concept_id: string;
-        aspect?: "new" | "advanced" | undefined;
+        aspect?: "new" | "advanced" | "preview" | undefined;
         note?: string | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
@@ -601,7 +601,7 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     product_completion: string;
     introduces: {
         concept_id: string;
-        aspect: "new" | "advanced";
+        aspect: "new" | "advanced" | "preview";
         note: string;
     }[];
 }, {
@@ -612,7 +612,7 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     feature_ids?: string[] | undefined;
     introduces?: {
         concept_id: string;
-        aspect?: "new" | "advanced" | undefined;
+        aspect?: "new" | "advanced" | "preview" | undefined;
         note?: string | undefined;
     }[] | undefined;
 }>;
@@ -2211,15 +2211,15 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         introduces: z.ZodDefault<z.ZodArray<z.ZodObject<{
             concept_id: z.ZodString;
-            aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+            aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
             note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         }, "strip", z.ZodTypeAny, {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }, {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
@@ -2230,7 +2230,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         product_completion: string;
         introduces: {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }[];
     }, {
@@ -2241,7 +2241,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids?: string[] | undefined;
         introduces?: {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }[] | undefined;
     }>, "many">>>;
@@ -2533,7 +2533,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         product_completion: string;
         introduces: {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }[];
     }[];
@@ -2824,7 +2824,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids?: string[] | undefined;
         introduces?: {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }[] | undefined;
     }[] | undefined;

package/dist/{hybridGraphSchema-BCgXicgA.d.cts → hybridGraphSchema-nrUeSwpU.d.ts}

@@ -563,15 +563,15 @@ declare const ProjectConceptLinkSchema: z.ZodObject<{
 }>;
 declare const ConceptIntroductionSchema: z.ZodObject<{
     concept_id: z.ZodString;
-    aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+    aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
     note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     concept_id: string;
-    aspect: "new" | "advanced";
+    aspect: "new" | "advanced" | "preview";
     note: string;
 }, {
     concept_id: string;
-    aspect?: "new" | "advanced" | undefined;
+    aspect?: "new" | "advanced" | "preview" | undefined;
     note?: string | undefined;
 }>;
 declare const DevelopmentPhaseSchema: z.ZodObject<{
@@ -582,15 +582,15 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     feature_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     introduces: z.ZodDefault<z.ZodArray<z.ZodObject<{
         concept_id: z.ZodString;
-        aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+        aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
         note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         concept_id: string;
-        aspect: "new" | "advanced";
+        aspect: "new" | "advanced" | "preview";
         note: string;
     }, {
         concept_id: string;
-        aspect?: "new" | "advanced" | undefined;
+        aspect?: "new" | "advanced" | "preview" | undefined;
         note?: string | undefined;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
@@ -601,7 +601,7 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     product_completion: string;
     introduces: {
         concept_id: string;
-        aspect: "new" | "advanced";
+        aspect: "new" | "advanced" | "preview";
         note: string;
     }[];
 }, {
@@ -612,7 +612,7 @@ declare const DevelopmentPhaseSchema: z.ZodObject<{
     feature_ids?: string[] | undefined;
     introduces?: {
         concept_id: string;
-        aspect?: "new" | "advanced" | undefined;
+        aspect?: "new" | "advanced" | "preview" | undefined;
         note?: string | undefined;
     }[] | undefined;
 }>;
@@ -2211,15 +2211,15 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         introduces: z.ZodDefault<z.ZodArray<z.ZodObject<{
             concept_id: z.ZodString;
-            aspect: z.ZodDefault<z.ZodEnum<["new", "advanced"]>>;
+            aspect: z.ZodDefault<z.ZodEnum<["new", "advanced", "preview"]>>;
             note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         }, "strip", z.ZodTypeAny, {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }, {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
@@ -2230,7 +2230,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         product_completion: string;
         introduces: {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }[];
     }, {
@@ -2241,7 +2241,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids?: string[] | undefined;
         introduces?: {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }[] | undefined;
     }>, "many">>>;
@@ -2533,7 +2533,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         product_completion: string;
         introduces: {
             concept_id: string;
-            aspect: "new" | "advanced";
+            aspect: "new" | "advanced" | "preview";
             note: string;
         }[];
     }[];
@@ -2824,7 +2824,7 @@ declare const HybridGraphSchema: z.ZodObject<{
         feature_ids?: string[] | undefined;
         introduces?: {
             concept_id: string;
-            aspect?: "new" | "advanced" | undefined;
+            aspect?: "new" | "advanced" | "preview" | undefined;
             note?: string | undefined;
         }[] | undefined;
     }[] | undefined;

package/dist/index.cjs

@@ -39,6 +39,22 @@ function validateCurriculumFeed(feed) {
   }
   const phaseIds = parsed.phases.map((p) => p.id);
   if (new Set(phaseIds).size !== phaseIds.length) throw new Error("curriculum feed contains duplicate phase ids");
+  if (parsed.phases.length > 0) {
+    const phaseIndexOf = /* @__PURE__ */ new Map();
+    parsed.phases.forEach((p, i) => {
+      for (const id of p.node_ids) phaseIndexOf.set(id, i);
+    });
+    for (const e of parsed.dependency_edges) {
+      const fromIdx = phaseIndexOf.get(e.from);
+      const toIdx = phaseIndexOf.get(e.to);
+      if (fromIdx === void 0 || toIdx === void 0) continue;
+      if (fromIdx > toIdx) {
+        throw new Error(
+          "curriculum feed teaching-order violation: prerequisite " + e.from + " (phase " + (fromIdx + 1) + ") is scheduled AFTER its consumer " + e.to + " (phase " + (toIdx + 1) + ")"
+        );
+      }
+    }
+  }
   return parsed;
 }
 exports.FeedKeywordsSchema = void 0; exports.FeedScaffoldCandidateSchema = void 0; exports.FeedNodeSchema = void 0; exports.FeedEdgeSchema = void 0; exports.FeedGroupingSchema = void 0; exports.FeedPhaseSchema = void 0; exports.CurriculumFeedSchema = void 0;
@@ -74,9 +90,10 @@ var init_curriculumFeedSchema = __esm({
       concept_ref: zod.z.string().nullable().default(null),
       // Progressive-completion bookkeeping (feed v2, additive):
       // phase_id = development phase that introduces/uses this node;
-      // introduce_aspect = how the phase teaches a concept node (first intro vs advanced revisit).
+      // introduce_aspect = how the phase teaches a concept node (first intro, advanced
+      // revisit, or preview — a light ULO awareness pass that is NOT the introduction).
       phase_id: zod.z.string().default(""),
-      introduce_aspect: zod.z.enum(["new", "advanced"]).nullable().default(null)
+      introduce_aspect: zod.z.enum(["new", "advanced", "preview"]).nullable().default(null)
     });
     exports.FeedEdgeSchema = zod.z.object({
       from: zod.z.string().min(1),
@@ -123,6 +140,9 @@ function stepMinutes(step) {
   const effort = step.effort ?? {};
   return Math.max(0, Math.round(num(effort.estimated_minutes, num(step.estimated_minutes, 45))));
 }
+function pushWarning(opts, message) {
+  (opts.warnings ?? (opts.warnings = [])).push(message);
+}
 function newKeywordsInOrder(nodes) {
   const seen = /* @__PURE__ */ new Set();
   for (const n of nodes) {
@@ -259,6 +279,7 @@ function emitFromHybrid(hybrid, opts) {
   }
   const emitCtx = [];
   const emittedConcepts = /* @__PURE__ */ new Set();
+  const previewsEmitted = /* @__PURE__ */ new Set();
   const linkList = arr(hybrid.links);
   for (const rp of rawPhases) {
     const pid = str(rp.id);
@@ -267,7 +288,8 @@ function emitFromHybrid(hybrid, opts) {
     const intros = arr(rp.introduces);
     const news = intros.filter((i) => str(i.aspect, "new") === "new");
     const advanced = intros.filter((i) => str(i.aspect) === "advanced");
-    for (const intro of [...news, ...advanced]) {
+    const previews = intros.filter((i) => str(i.aspect) === "preview");
+    for (const intro of [...news, ...advanced, ...previews]) {
       const cid = str(intro.concept_id);
       const c = conceptById.get(cid);
       if (!c) {
@@ -276,6 +298,37 @@ function emitFromHybrid(hybrid, opts) {
       if (str(intro.aspect, "new") === "advanced" && !emittedConcepts.has(cid)) {
         throw new Error("Phase " + pid + " advanced-revisits concept " + cid + " that was never emitted - fail-closed");
       }
+      if (str(intro.aspect, "new") === "preview") {
+        if (emittedConcepts.has(cid)) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " that was already introduced - preview must precede the anchor teach - fail-closed");
+        }
+        if (previewsEmitted.has(cid)) {
+          throw new Error("Phase " + pid + " duplicate preview of concept " + cid + " - fail-closed");
+        }
+        const pidIdx = rawPhases.findIndex((rp2) => str(rp2.id) === pid);
+        const anchorIdx = rawPhases.findIndex((rp2) => arr(rp2.introduces).some((i2) => str(i2.concept_id) === cid && str(i2.aspect, "new") !== "preview"));
+        if (anchorIdx < 0) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " that is never fully introduced in any phase - fail-closed");
+        }
+        if (pidIdx >= anchorIdx) {
+          throw new Error("Phase " + pid + " previews concept " + cid + " whose anchor introduction is not in a LATER phase - fail-closed");
+        }
+        previewsEmitted.add(cid);
+        const prevNode = feedNodeFromConcept(c);
+        prevNode.id = cid + "__PREV" + pad22(order);
+        prevNode.name = str(c.name, cid) + " (preview)";
+        prevNode.phase_id = pid;
+        prevNode.introduce_aspect = "preview";
+        prevNode.estimated_minutes = Math.max(5, Math.round(prevNode.estimated_minutes * 0.25));
+        prevNode.depth_hint = "ulo";
+        prevNode.bloom_hint = "Understand";
+        prevNode.concept_codes = [str(c.code) || cid];
+        prevNode.keywords = { all: strs(c.keywords), new: [], prerequisite: [] };
+        prevNode.scaffolding = { scaffold_candidates: [], core_value_minutes: 0 };
+        nodes.push(prevNode);
+        conceptOrder.push(prevNode.id);
+        continue;
+      }
       if (!emittedConcepts.has(cid)) {
         const node = feedNodeFromConcept(c);
         node.phase_id = pid;
@@ -331,6 +384,17 @@ function emitFromHybrid(hybrid, opts) {
     }
     phaseNodeIds.push(ids);
   }
+  const placed = new Set(phaseNodeIds.flat());
+  const orderedNodes = [];
+  for (const ids of phaseNodeIds) {
+    for (const id of ids) {
+      const n = nodes.find((x) => x.id === id);
+      if (n) orderedNodes.push(n);
+    }
+  }
+  for (const n of nodes) if (!placed.has(n.id)) orderedNodes.push(n);
+  nodes.length = 0;
+  nodes.push(...orderedNodes);
   const edgeSeen = new Set(edges.map((e) => e.from + ">" + e.to));
   const pushEdge = (from, to, reason) => {
     const key = from + ">" + to;
@@ -345,6 +409,14 @@ function emitFromHybrid(hybrid, opts) {
     const firstStep = (stepIdsByFeature.get(fid) || [])[0];
     if (!firstStep) continue;
     const depth = str(l.depth, "cio");
+    const anchorNode = nodes.find((n2) => n2.kind === "concept" && n2.concept_ref === cid && n2.introduce_aspect === "new");
+    const stepNode = nodes.find((n2) => n2.id === firstStep);
+    const anchorPhaseIdx = anchorNode ? emitCtx.findIndex((c2) => c2.id === anchorNode.phase_id) : -1;
+    const stepPhaseIdx = stepNode ? emitCtx.findIndex((c2) => c2.id === stepNode.phase_id) : -1;
+    if (emitCtx.length > 0 && anchorPhaseIdx > stepPhaseIdx) {
+      pushWarning(opts, "hybrid link drift: concept " + cid + " is fully taught in a later phase than consumer " + firstStep + " (a preview covers the dependency)");
+      continue;
+    }
     pushEdge(cid, firstStep, str(l.relationship, "hybrid link") + " [" + depth + "]");
     for (const n of nodes) {
       if (n.kind === "concept" && n.concept_ref === cid && n.introduce_aspect === "advanced" && n.phase_id === str(l.phase_id)) {
@@ -363,6 +435,21 @@ function emitFromHybrid(hybrid, opts) {
     for (const k of n.keywords?.prerequisite ?? []) {
       const src = introducer.get(k.toLowerCase());
       if (!src || src === n.id) continue;
+      const srcNode = nodes.find((x) => x.id === src);
+      const phaseOf = (id) => {
+        const n2 = nodes.find((x) => x.id === id);
+        return n2 ? emitCtx.findIndex((c) => c.id === n2.phase_id) : -1;
+      };
+      const conceptOvertaken = n.kind === "concept" && srcNode?.kind === "product_step";
+      const fromPhase = phaseOf(src);
+      const toPhase = phaseOf(n.id);
+      if (conceptOvertaken || emitCtx.length > 0 && fromPhase > toPhase) {
+        pushWarning(
+          opts,
+          "keyword-order drift: introducer " + src + " sits in a later phase than consumer " + n.id + ' (keyword "' + k + '") \u2014 host should move the introducer earlier'
+        );
+        continue;
+      }
       if (feedOrder.get(src) < feedOrder.get(n.id)) pushEdge(src, n.id, "keyword prerequisite [" + k + "]");
     }
   }
@@ -935,8 +1022,8 @@ var ProjectConceptLinkSchema = zod.z.object({
 });
 var ConceptIntroductionSchema = zod.z.object({
   concept_id: zod.z.string().describe("Concept ID from knowledge_graph"),
-  aspect: zod.z.enum(["new", "advanced"]).default("new").describe(
-    "new = concept introduced for the first time; advanced = previously introduced concept revisited at higher depth"
+  aspect: zod.z.enum(["new", "advanced", "preview"]).default("new").describe(
+    "new = concept introduced for the first time; advanced = previously introduced concept revisited at higher depth; preview = light ULO awareness pass ('know it exists') placed at the consuming phase BEFORE the full introduction \u2014 the anchor phase still owns the full 'new' teach"
   ),
   note: zod.z.string().optional().default("").describe("Which advanced aspect of the concept this phase develops")
 });
@@ -4925,6 +5012,8 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
   const phases = [];
   const featurePhase = /* @__PURE__ */ new Map();
   const newIntroPhase = /* @__PURE__ */ new Map();
+  const previewsSeen = /* @__PURE__ */ new Set();
+  const previewPhase = /* @__PURE__ */ new Map();
   const errors = [];
   plan.forEach((rp, idx) => {
     const id = String(rp.id || "PH" + (idx + 1));
@@ -4956,7 +5045,22 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
         errors.push("Phase " + id + ": introduces unknown concept " + cid);
         continue;
       }
-      const aspect = String(ri.aspect || "new") === "advanced" ? "advanced" : "new";
+      const rawAspect = String(ri.aspect || "new");
+      const aspect = rawAspect === "advanced" || rawAspect === "preview" ? rawAspect : "new";
+      if (aspect === "preview") {
+        if (newIntroPhase.has(cid)) {
+          errors.push("Phase " + id + ": preview of " + cid + " after its new introduction in phase " + newIntroPhase.get(cid) + " - preview must precede the anchor teach");
+          continue;
+        }
+        if (previewsSeen.has(cid)) {
+          errors.push("Phase " + id + ": duplicate preview of " + cid);
+          continue;
+        }
+        previewsSeen.add(cid);
+        previewPhase.set(cid, order);
+        introductions.push({ concept_id: cid, aspect, note: String(ri.note || "") });
+        continue;
+      }
       if (aspect === "advanced") {
         const first = newIntroPhase.get(cid);
         if (first === void 0) {
@@ -5004,10 +5108,17 @@ function auditPhasePlan(plan, features, concepts, links, warnings, log) {
   }
   for (const [cid, consumerOrder] of firstConsumerPhase) {
     const intro = newIntroPhase.get(cid);
-    if (intro === void 0) {
+    const prev = previewPhase.get(cid);
+    if (intro === void 0 && prev === 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");
+    } else if (intro !== void 0 && intro > consumerOrder && (prev === void 0 || prev > consumerOrder)) {
+      errors.push("Concept " + cid + " introduced in phase " + intro + " but first consumed in phase " + consumerOrder + " - introduction must come no later than first consumption (or a preview must cover the dependency)");
+    }
+  }
+  for (const [cid, pOrder] of previewPhase) {
+    const anchor = newIntroPhase.get(cid);
+    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");
     }
   }
   return { phases, errors };
@@ -5023,7 +5134,7 @@ 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.\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 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 MAX_DECOMPOSE_ATTEMPTS = 3;
   let auditErrors = [];