@thanh01.pmt/domain-kit 0.2.1 → 0.4.0

package/README.md

@@ -151,7 +151,8 @@ const feed = emitCurriculumFeed(result.projectGraph);  // or knowledgeGraph or h
 console.log(feed.learning_nodes.length);    // unified nodes ready for planner
 console.log(feed.dependency_edges.length);  // knowledge + task edges
 console.log(feed.suggested_groupings);      // feature/category groupings
-// Each node has: bloom_hint, depth_hint, keywords.new/.prerequisite
+console.log(feed.phases.length);            // non-empty ⇒ learning_nodes are in teaching order (phases define units)
+// Each node has: bloom_hint, depth_hint, keywords.new/.prerequisite, introduce_aspect, user_visible_deliverable
 ```
 
 ---
@@ -399,10 +400,11 @@ All schemas are Zod-validated TypeScript types.
 | `DomainProfileSchema` | `domainProfileSchema.ts` | Domain detection output |
 | `HardwareFeatureExtension` | `domainExtensions.ts` | Hardware overlay (wiring, materials) |
 | `ThreeDesignFeatureExtension` | `domainExtensions.ts` | 3D Design overlay (shapes, dimensions) |
-| `CurriculumFeedSchema` | `curriculumFeedSchema.ts` | Planner-ready normalized feed (nodes, edges, groupings) |
+| `CurriculumFeedSchema` | `curriculumFeedSchema.ts` | Planner-ready normalized feed (nodes, edges, groupings, phases) |
 | `FeedNodeSchema` | `curriculumFeedSchema.ts` | Individual learning node (concept, skill, or product step) |
 | `FeedEdgeSchema` | `curriculumFeedSchema.ts` | Dependency edge (knowledge or task) |
 | `FeedGroupingSchema` | `curriculumFeedSchema.ts` | Suggested grouping of nodes (feature or category) |
+| `FeedPhaseSchema` | `curriculumFeedSchema.ts` | Development phase — when non-empty, defines teaching sequence and unit structure |
 
 ### Key Types
 
@@ -486,9 +488,10 @@ type AssembledRoadmap = {
 type CurriculumFeed = {
   schema_version: 2;
   source: { graph_type: 'project_graph' | 'knowledge_graph' | 'hybrid_graph'; warnings: string[]; hallucination_count: number };
-  learning_nodes: FeedNode[];
+  learning_nodes: FeedNode[];   // in TEACHING ORDER when phases[] is non-empty
   dependency_edges: FeedEdge[];
   suggested_groupings: FeedGrouping[];
+  phases: FeedPhase[];          // when non-empty, THESE — not suggested_groupings — define the teaching sequence and unit structure
 }
 
 type FeedNode = {
@@ -505,6 +508,20 @@ type FeedNode = {
   references: { file: string; evidence: string }[];
   feature_id: string | null;
   concept_ref: string | null;
+  phase_id: string;                          // development phase that introduces/uses this node ('' on legacy feeds)
+  introduce_aspect: 'new' | 'advanced' | 'preview' | null;  // first intro / advanced revisit / preview priming
+  user_visible_deliverable: string;          // step's outcome.user_visible — checkpoint candidate for session cutting ('' on concept nodes)
+  depth_variants?: { ulo: number; cio: number; sio: number };  // minutes per depth level — reconciler price list (ULO ≤ CIO ≤ SIO)
+  depth_scaffold_candidates?: { from_depth: 'ulo' | 'cio' | 'sio'; to_depth: 'ulo' | 'cio' | 'sio'; minutes_saved: number; reason: string }[];  // DEPTH downgrades (SIO→CIO, CIO→ULO) — parallel to scaffold_candidates
+  is_core: boolean;                          // Master-Tree core concept — never depth-downgraded; escalate instead
+}
+
+type FeedPhase = {
+  id: string;
+  order: number;             // 1-based teaching order
+  name: string;
+  product_completion: string;
+  node_ids: string[];        // nodes of this phase, already in teaching order
 }
 
 type FeedEdge = {
@@ -640,19 +657,26 @@ const feed = emitCurriculumFeed(graph, {
 });
 
 // Returns CurriculumFeed with:
-// - learning_nodes[]     — unified node format (concept | skill | product_step)
+// - learning_nodes[]     — unified node format (concept | skill | product_step), in teaching order when phases[] is non-empty
 // - dependency_edges[]   — knowledge (prerequisite) or task (build order) edges
-// - suggested_groupings[] — feature or category groupings
-// - Each node has: bloom_hint, depth_hint (ulo/cio/sio), keywords.new vs .prerequisite
+// - suggested_groupings[] — feature or category groupings (layout hint only)
+// - phases[]             — development phases; when non-empty, the teaching sequence + unit structure
+// - Each node has: bloom_hint, depth_hint (ulo/cio/sio), keywords.new vs .prerequisite,
+//   introduce_aspect (new/advanced/preview), user_visible_deliverable,
+//   depth_variants + depth_scaffold_candidates + is_core (depth-reconcile inputs)
 ```
 
 **Key behaviors:**
-- **Hybrid graphs**: concepts emitted first (prerequisite-first), then project steps; hybrid links carry depth hint onto step nodes; `estimated_prereq_minutes` accumulated per concept node
+- **Teaching-order emission (contract, 2026-09-18):** when a hybrid graph carries `phases[]`, the `nodes` array follows the **phase teaching sequence** — the order in the file IS the order in the classroom. The former "concepts emitted first, then steps" array layout is ABOLISHED: it contradicted phase order, fabricated backwards prerequisite edges, and caused the planner's "Teaching-order violation" failure (see postmortem 2026-09-17 §9)
+- **No fabricated backwards edges:** when a keyword consumer sits in an EARLIER phase than the concept's anchor teach (and no preview covers it), the emitter does NOT invent a dependency edge — it records a drift **warning** instead (`hybrid link drift: …`); the host decides, the emitter reports
+- **Overtake guard:** a product step must never become the introducer of a concept's vocabulary; the first appearance of a keyword belongs to the concept (or its preview node) that teaches it
+- **Preview priming (aspect `preview`, kit ≥0.3.0):** a phase may declare a light awareness pass for a concept whose anchor teach lives in a LATER phase — emitted as node `<cid>__PREVxx` with depth `ulo`, bloom `Understand`, ~25% minutes (min 5), `keywords.all` (making it the legitimate vocabulary introducer), no prerequisite edges, no scaffolding. Five fail-closed emission rules: unknown concept, already-introduced concept, duplicate preview, no anchor anywhere, anchor not in a later phase
 - **Knowledge graphs**: concepts + prerequisite edges + category groupings
 - **Project graphs**: features → steps + depends_on edges + feature groupings
 - **Pass-through**: if input already has `learning_nodes[]`, validates and returns as-is
 - **Legacy rejection**: throws descriptive error if graph has `implementation.tasks` but no `features[].steps` (old knowledge-tree format)
-- **New/prerequisite keywords**: computed in emission order — first appearance = new, seen before = prerequisite
+- **New/prerequisite keywords**: computed in **teaching order** (phase sequence when phases exist, array order otherwise) — first appearance = new, seen before = prerequisite. Anchoring keywords to array position instead of teaching order is the exact assumption that caused the 2026-09-17 incident
+- **Fail-closed validation**: output is validated before return — duplicate IDs, unresolvable edges, self-loops, non-empty, **and the teaching-order invariant**: when phases define the sequence, a prerequisite must live in the same or an EARLIER phase than its consumer (a violation throws at emission, never defers to the planner)
 
 ### Parsers
 
@@ -723,8 +747,15 @@ STEP 9: Feed Emission
   → Convert project_graph → FeedNode[] (kind: product_step) + FeatureGroupings
   → Convert knowledge_graph → FeedNode[] (kind: concept) + CategoryGroupings
   → Convert hybrid_graph → combined nodes + knowledge/task edges + hybrid link depth hints
-  → Compute new/prerequisite keywords in emission order
-  → Validate: fail-closed (duplicate IDs, edge resolution, self-loops, non-empty)
+  → Project steps: project outcome.user_visible onto user_visible_deliverable (checkpoint candidate)
+  → Concept nodes: emit depth_variants (ULO ≤ CIO ≤ SIO minutes) + depth_scaffold_candidates + is_core
+  → Teaching order: when phases[] exist, nodes are emitted in phase sequence; new/prerequisite
+    keywords computed in TEACHING order (first appearance = new), never array position
+  → Preview priming: phase-declared __PREVxx awareness nodes carry keywords.all (legitimate
+    vocabulary introducer) without fabricating prerequisite edges
+  → Validate: fail-closed (duplicate IDs, edge resolution, self-loops, non-empty, duplicate
+    phase ids, and the teaching-order invariant: a prerequisite must live in the same or an
+    EARLIER phase than its consumer — a backwards edge throws at emission, never in the planner)
 ```
 
 ### Knowledge Graph Pipeline (Concept-Driven)
@@ -949,7 +980,7 @@ import {
   ProjectGraphSchema, KnowledgeGraphSchema, HybridGraphSchema,
   DomainProfileSchema, ConceptMappingSchema, AssembledRoadmapSchema,
   KnowledgeConceptSchema, KnowledgeLearningPathStepSchema,
-  CurriculumFeedSchema, FeedNodeSchema, FeedEdgeSchema, FeedGroupingSchema,
+  CurriculumFeedSchema, FeedNodeSchema, FeedEdgeSchema, FeedGroupingSchema, FeedPhaseSchema,
 } from '@thanh01.pmt/domain-kit';
 
 // Roadmap assembly

package/dist/{chunk-CRN6D4HG.mjs → chunk-HILSUZOF.mjs}

@@ -2120,6 +2120,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));
@@ -2151,7 +2153,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) {
@@ -2199,10 +2216,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 };
@@ -2218,7 +2242,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 = [];
@@ -2256,6 +2280,6 @@ async function decomposePhases(args) {
   return phases;
 }
 
-export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, auditSyllabusCoverage, breakPrerequisiteCycles, cioActionSlug, cioCode, conceptCodeFromName, createLlmClient, detectPrerequisiteCycles, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, llmChatJson, sioCode, standardStatement, techTagFor, uloCode, verifyKnowledgeGraph, verifyProjectGraph };
-//# sourceMappingURL=chunk-CRN6D4HG.mjs.map
-//# sourceMappingURL=chunk-CRN6D4HG.mjs.map
+export { CIO_CODE_RE, CONCEPT_CODE_RE, LEARNER_CLAUSE, SIO_CODE_RE, ULO_CODE_RE, assignConceptCodes, auditDepthLayers, auditPhasePlan, auditSyllabusCoverage, breakPrerequisiteCycles, cioActionSlug, cioCode, conceptCodeFromName, createLlmClient, detectPrerequisiteCycles, escalateAndMapConcepts, extractFeatureSteps, extractFeatureStepsBatched, extractProjectOverview, extractScaffold, generateHybridGraph, generateKnowledgeGraph, llmChatJson, sioCode, standardStatement, techTagFor, uloCode, verifyKnowledgeGraph, verifyProjectGraph };
+//# sourceMappingURL=chunk-HILSUZOF.mjs.map
+//# sourceMappingURL=chunk-HILSUZOF.mjs.map