@thanh01.pmt/domain-kit 0.3.0 → 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-Y7MRFFDJ.mjs → chunk-HILSUZOF.mjs}

@@ -2280,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-Y7MRFFDJ.mjs.map
-//# sourceMappingURL=chunk-Y7MRFFDJ.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