@thanh01.pmt/curriculum-kit 1.4.18 → 1.4.20

package/dist/workflow/index.cjs

@@ -18878,6 +18878,268 @@ ${lines.join("\n")}
 - For example: if canonical section is "Computational Thinking Focus", your heading must be "## [REQUIRED] ${headings["Computational Thinking Focus"] || "Computational Thinking Focus"}".`;
 }
 
+// src/services/curriculumHorizon.ts
+init_errors();
+var DETAILED_BRIDGE_WINDOW = 2;
+var BOUNDARY_PEEK_WINDOW = 2;
+function parseAllSessions(plan, frameworkMarkdown) {
+  if (plan) {
+    const rawSessions = Array.isArray(plan.sessions) ? plan.sessions : Array.isArray(plan) ? plan : [];
+    if (rawSessions.length > 0) {
+      return rawSessions.map((s, idx) => ({
+        id: s.id || `L${String(idx + 1).padStart(2, "0")}`,
+        order: typeof s.order === "number" ? s.order : idx + 1,
+        title: s.title || "",
+        prose_objective: s.prose_objective || s.objective || "",
+        new_keywords: Array.isArray(s.new_keywords) ? s.new_keywords : Array.isArray(s.keywords) ? s.keywords : [],
+        prerequisite_keywords: Array.isArray(s.prerequisite_keywords) ? s.prerequisite_keywords : [],
+        depth_assignments: Array.isArray(s.depth_assignments) ? s.depth_assignments : []
+      }));
+    }
+  }
+  if (frameworkMarkdown && typeof frameworkMarkdown === "string") {
+    const lines = frameworkMarkdown.split("\n");
+    let headerCols = [];
+    const sessions = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("|")) continue;
+      const cols = trimmed.split("|").slice(1, -1).map((c) => c.trim());
+      const lower = cols.map((c) => c.toLowerCase());
+      if (lower.some((c) => c.includes("lesson code") || c === "m\xE3 b\xE0i" || c.includes("m\xE3 b\xE0i h\u1ECDc"))) {
+        headerCols = cols;
+        continue;
+      }
+      if (/^[-: |]+$/.test(trimmed.slice(1, -1))) continue;
+      if (cols.length < 3) continue;
+      let lessonCode = "";
+      let title = "";
+      let objective = "";
+      let concept = "";
+      let keywordsStr = "";
+      if (headerCols.length > 0) {
+        const col = (name) => {
+          const idx = headerCols.findIndex((h) => h.toLowerCase().includes(name));
+          return idx >= 0 ? cols[idx] || "" : "";
+        };
+        lessonCode = (col("lesson code") || col("m\xE3 b\xE0i") || cols[1] || "").replace(/\*\*/g, "").trim();
+        title = (col("title") || col("t\xEAn") || cols[2] || "").replace(/\*\*/g, "").trim();
+        objective = col("learning objective") || col("objective") || col("m\u1EE5c ti\xEAu") || "";
+        concept = col("key concept") || col("concept") || col("kh\xE1i ni\u1EC7m") || "";
+        keywordsStr = col("keywords") || col("t\u1EEB kh\xF3a") || "";
+      } else {
+        lessonCode = (cols[1] || "").replace(/\*\*/g, "").trim();
+        title = (cols[2] || "").replace(/\*\*/g, "").trim();
+        objective = cols[5] || "";
+        concept = cols[4] || "";
+      }
+      if (lessonCode && /^[A-Za-z0-9_\-]+$/.test(lessonCode)) {
+        const keywords = keywordsStr ? keywordsStr.split(/[,;\n]/).map((k) => k.trim().replace(/^`|`$/g, "")).filter(Boolean) : concept ? concept.split(/[,;\n]/).map((k) => k.trim().replace(/^`|`$/g, "")).filter(Boolean) : [];
+        sessions.push({
+          id: lessonCode,
+          order: sessions.length + 1,
+          title: title || lessonCode,
+          prose_objective: objective,
+          new_keywords: keywords
+        });
+      }
+    }
+    if (sessions.length > 0) {
+      return sessions;
+    }
+  }
+  return [];
+}
+async function extractCurriculumHorizon(opts) {
+  const { plan, frameworkMarkdown, targetLessonId, storage, projectId } = opts;
+  const sessions = parseAllSessions(plan, frameworkMarkdown);
+  if (sessions.length === 0) {
+    throw new CurriculumError({
+      errorCode: "ERR_LESSON_NOT_IN_SOT",
+      lessonId: targetLessonId,
+      message: `[CurriculumHorizon] No sessions could be parsed from CURRICULUM_PLAN.json or CURRICULUM_FRAMEWORK.md. Fail fast \u2014 cannot construct curriculum horizon without SOT.`,
+      suggestedAction: "Ensure CURRICULUM_PLAN.json or CURRICULUM_FRAMEWORK.md is generated and contains valid sessions.",
+      retryable: false
+    });
+  }
+  const targetCodePattern = new RegExp("^" + targetLessonId.replace(/_/g, "[_-]") + "$", "i");
+  const targetIndex = sessions.findIndex(
+    (s) => s.id === targetLessonId || targetCodePattern.test(s.id)
+  );
+  if (targetIndex < 0) {
+    throw new CurriculumError({
+      errorCode: "ERR_LESSON_NOT_IN_SOT",
+      lessonId: targetLessonId,
+      message: `[CurriculumHorizon] Lesson "${targetLessonId}" was not found among the ${sessions.length} planned sessions. Fail fast \u2014 refusing to generate unanchored lesson.`,
+      suggestedAction: `Check lesson id against planned sessions: [${sessions.map((s) => s.id).join(", ")}]`,
+      retryable: false
+    });
+  }
+  const currentSession = sessions[targetIndex];
+  const compactEnd = Math.max(0, targetIndex - DETAILED_BRIDGE_WINDOW);
+  const compactSessions = sessions.slice(0, compactEnd);
+  const masteredKeywords = Array.from(
+    new Set(
+      compactSessions.flatMap((s) => s.new_keywords || []).map((k) => k.trim()).filter(Boolean)
+    )
+  );
+  const masteredConcepts = Array.from(
+    new Set(
+      compactSessions.map((s) => s.title || s.prose_objective || "").map((t) => t.trim()).filter(Boolean)
+    )
+  );
+  const bridgeStart = Math.max(0, targetIndex - DETAILED_BRIDGE_WINDOW);
+  const bridgeSessions = sessions.slice(bridgeStart, targetIndex);
+  const detailedBridge = [];
+  for (const session of bridgeSessions) {
+    const bridgeIndex = sessions.indexOf(session) + 1;
+    const bridge = {
+      lessonId: session.id,
+      lessonIndex: bridgeIndex,
+      title: session.title,
+      proseObjective: session.prose_objective,
+      keywords: session.new_keywords || []
+    };
+    if (storage && projectId) {
+      try {
+        const candidates = [
+          `_content/${session.id.replace(/_L\d+$/, "")}/LESSON_${session.id}.md`,
+          `_content/LESSON_${session.id}.md`,
+          `LESSON_${session.id}.md`
+        ];
+        let lessonMd = "";
+        for (const c of candidates) {
+          try {
+            const raw = await storage.readArtifact(projectId, c);
+            if (raw) {
+              lessonMd = raw;
+              break;
+            }
+          } catch {
+          }
+        }
+        if (lessonMd) {
+          const ledger = extractSymbolLedger(lessonMd);
+          if (ledger.primarySymbol || ledger.entryFileName || ledger.keySymbols.length > 0) {
+            bridge.symbolLedger = {
+              primaryStructOrClass: ledger.primarySymbol,
+              mainEntryFile: ledger.entryFileName,
+              keyVariables: ledger.keySymbols
+            };
+          }
+        }
+      } catch {
+      }
+    }
+    detailedBridge.push(bridge);
+  }
+  const peekStart = targetIndex + 1;
+  const peekEnd = Math.min(sessions.length, peekStart + BOUNDARY_PEEK_WINDOW);
+  const boundaryPeek = sessions.slice(peekStart, peekEnd).map((s, idx) => ({
+    lessonId: s.id,
+    lessonIndex: peekStart + idx + 1,
+    title: s.title,
+    keywords: s.new_keywords || []
+  }));
+  return {
+    targetLessonId,
+    targetLessonIndex: targetIndex + 1,
+    totalLessons: sessions.length,
+    targetTitle: currentSession.title,
+    targetKeywords: currentSession.new_keywords || [],
+    compactMasterySet: {
+      masteredKeywords,
+      masteredConcepts
+    },
+    detailedBridge,
+    boundaryPeek
+  };
+}
+function renderHorizonPromptBlock(horizon) {
+  const {
+    targetLessonId,
+    targetLessonIndex,
+    totalLessons,
+    targetTitle,
+    targetKeywords,
+    compactMasterySet,
+    detailedBridge,
+    boundaryPeek
+  } = horizon;
+  const lines = [
+    `# \u{1F9ED} CURRICULUM HORIZON & SCAFFOLDING MATRIX (Lesson ${targetLessonIndex}/${totalLessons}: "${targetTitle}" [${targetLessonId}])`
+  ];
+  if (compactMasterySet.masteredKeywords.length > 0 || compactMasterySet.masteredConcepts.length > 0) {
+    const rawKeywords = compactMasterySet.masteredKeywords;
+    const displayedKeywords = rawKeywords.length > 20 ? rawKeywords.slice(-20) : rawKeywords;
+    const vocab = displayedKeywords.map((k) => `\`${k}\``).join(", ");
+    const moreSuffix = rawKeywords.length > 20 ? ` *(+${rawKeywords.length - 20} earlier terms)*` : "";
+    const concepts = compactMasterySet.masteredConcepts.length > 0 ? `
+- **Prior Concept Foundations:** ${compactMasterySet.masteredConcepts.slice(-3).join("; ")}` : "";
+    lines.push(
+      `
+## 1. \u{1F393} MASTERED VOCABULARY (Prior Lessons 1..${Math.max(1, targetLessonIndex - 3)} \u2014 Compact Set):`,
+      `- **Mastered Terms & Syntax:** ${vocab || "(Core fundamentals)"}${moreSuffix}${concepts}`
+    );
+  } else if (targetLessonIndex === 1) {
+    lines.push(
+      `
+## 1. \u{1F393} PRIOR KNOWLEDGE FRONTIER:`,
+      `- **Entry Point:** Inaugural lesson (Lesson 1/${totalLessons}). Students have no prior course vocabulary. All concepts must be introduced from baseline.`
+    );
+  }
+  if (detailedBridge.length > 0) {
+    lines.push(`
+## 2. \u{1F309} IMMEDIATE PREDECESSOR CONTEXT (Bridge Lessons):`);
+    for (const bridge of detailedBridge) {
+      lines.push(`### Lesson ${bridge.lessonIndex} (${bridge.lessonId}): ${bridge.title}`);
+      if (bridge.proseObjective) {
+        const obj = bridge.proseObjective.length > 120 ? bridge.proseObjective.slice(0, 117) + "..." : bridge.proseObjective;
+        lines.push(`- **Objective:** ${obj}`);
+      }
+      if (bridge.keywords.length > 0) {
+        lines.push(`- **Keywords:** ${bridge.keywords.map((k) => `\`${k}\``).join(", ")}`);
+      }
+      if (bridge.symbolLedger) {
+        const parts = [];
+        if (bridge.symbolLedger.primaryStructOrClass) {
+          parts.push(`Primary Struct: \`${bridge.symbolLedger.primaryStructOrClass}\``);
+        }
+        if (bridge.symbolLedger.mainEntryFile) {
+          parts.push(`Entry File: \`${bridge.symbolLedger.mainEntryFile}\``);
+        }
+        if (bridge.symbolLedger.keyVariables?.length) {
+          parts.push(`Symbols: ${bridge.symbolLedger.keyVariables.map((v) => `\`${v}\``).join(", ")}`);
+        }
+        if (parts.length > 0) {
+          lines.push(`- **Code Symbol Ledger:** ${parts.join(" | ")}`);
+        }
+      }
+    }
+    lines.push(
+      `\u{1F449} INSTRUCTION: Seamlessly connect the opening Hook and Guided Practice by referencing the student's recent work from Lesson ${detailedBridge[detailedBridge.length - 1]?.lessonIndex}.`
+    );
+  }
+  const currentKeywordsStr = targetKeywords.length > 0 ? targetKeywords.map((k) => `\`${k}\``).join(", ") : "`Current Lesson Concepts`";
+  lines.push(
+    `
+## 3. \u{1F3AF} ALLOWED DESIGN SPACE (Positive-Only Allow List):`,
+    `- **Student Toolkit:** Mastered Vocabulary + Immediate Bridge Keywords + Current Lesson Scope (${currentKeywordsStr}).`,
+    `- **MANDATE:** ALL extension challenges (EXT), hands-on activities (ACT), and assessment questions (QUIZ) MUST be 100% solvable using ONLY items within this toolkit. Do NOT require unintroduced APIs!`
+  );
+  if (boundaryPeek.length > 0) {
+    const nextLesson = boundaryPeek[0];
+    const nextKeywords = nextLesson.keywords.length > 0 ? nextLesson.keywords.map((k) => `\`${k}\``).join(", ") : "upcoming features";
+    lines.push(
+      `
+## 4. \u{1F6A7} BOUNDARY (Next Lesson Peek):`,
+      `- **Upcoming Lesson ${nextLesson.lessonIndex} ("${nextLesson.title}"):** Introduces ${nextKeywords}.`,
+      `- **BOUNDARY MANDATE:** These concepts are NOT yet available to the student. Do not introduce or require these future concepts.`
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/services/contextBuilder.ts
 var DEFAULT_LESSON_PRIORITIES = [
   "Symbol & Identifier Ledger",
@@ -19438,6 +19700,20 @@ async function generateSingleArtifact(req) {
    - Entry Source File: \`${symbolLedger.entryFileName || symbolLedger.primarySymbol + ".swift"}\`
    - Key Identifiers to inherit: ${symbolLedger.keySymbols.map((s) => `\`${s}\``).join(", ")}
    - INVARIANT: You MUST use these exact identifier names in all code examples, exercises, and starter templates. Do NOT invent conflicting struct or class names.` : "";
+  let horizon = contextSot.horizon || null;
+  if (!horizon && (contextSot.plan || contextSot.framework) && lessonId) {
+    try {
+      horizon = await extractCurriculumHorizon({
+        plan: contextSot.plan,
+        frameworkMarkdown: contextSot.framework,
+        targetLessonId: lessonId
+      });
+    } catch {
+    }
+  }
+  const horizonPrompt = horizon ? `
+
+${renderHorizonPromptBlock(horizon)}` : "";
   const systemPrompt = `You are ${meta.persona}, an expert Curriculum & Pedagogical Specialist in the Curriculum OS Multi-Agent Team.
 Your task is to author a canonical, publication-grade learning artifact of type "${artifactType.toUpperCase()}".
 
@@ -19451,7 +19727,7 @@ ${headingDirective}
 6. DOMAIN & TECH STACK GUARDRAILS:
 ${domainGuardrail}
 ${symbolLedgerPrompt}
-8. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.${artifactSpecializedPrompt}${mediaPolicy ? `
+8. OUTPUT INTEGRITY: Output clean Markdown starting directly with YAML frontmatter. Do not wrap entire response in triple backticks.${artifactSpecializedPrompt}${horizonPrompt}${mediaPolicy ? `
 
 IMAGE PLANNING (media ledger) \u2014 QUOTA GEN: t\u1ED1i \u0111a ${mediaPolicy.maxGenImagesPerArtifact} \u1EA3nh AI cho artifact n\xE0y (\u1EA3nh search kho kh\xF4ng gi\u1EDBi h\u1EA1n).
 Khi n\u1ED9i dung c\u1EA7n minh h\u1ECDa (diagram quy tr\xECnh, s\u01A1 \u0111\u1ED3 kh\xE1i ni\u1EC7m, step-by-step visual), ch\xE8n placeholder \u0111\xFAng format [IMAGE: slug] (slug ch\u1EEF th\u01B0\u1EDDng-g\u1EA1ch ngang, unique trong b\xE0i, vd img-for-loop-diagram) T\u1EA0I \u0110\xDANG CH\u1ED6 c\u1EA7n \u1EA3nh, tr\xEAn d\xF2ng ri\xEAng. KH\xD4NG t\u1EF1 sinh \u1EA3nh, KH\xD4NG d\xF9ng markdown image \u2014 placeholder s\u1EBD \u0111\u01B0\u1EE3c thay b\u1EB1ng \u1EA3nh th\u1EADt sau khi Media Curator duy\u1EC7t. Ch\u1EC9 \u0111\u1EB7t cho \u1EA3nh TH\u1EF0C S\u1EF0 c\u1EA7n thi\u1EBFt.` : ""}`;
@@ -19932,13 +20208,9 @@ ${includeUnitTests ? "- Unit Testing: Provide automated assertions or test runne
    - Exact quantities calculated for ${studentCount} students.
    - Component specifications, estimated unit cost, and affordable alternatives.`;
     case "ext": {
-      const lessonIdxMatch = (req.lessonId || "").match(/L0*(\d+)/i);
-      const lessonIdx = lessonIdxMatch ? parseInt(lessonIdxMatch[1], 10) : 1;
-      const isEarlyLesson = lessonIdx <= 4;
-      const zpdCeilingRule = isEarlyLesson ? `- \u{1F6D1} ZPD COMPLEXITY CEILING (FOUNDATIONAL LESSON #${lessonIdx}):
-  \u2022 SCOPE LOCK: This is an early foundational lesson. The extension challenge MUST focus on creative design variations, parameterization, or edge cases of the current lesson concepts ONLY.
-  \u2022 STRICTLY FORBIDDEN: NEVER introduce advanced mechanisms from future lessons (No complex event buses, No remote network/API calls, No persistent databases, No async concurrency, No out-of-scope hardware/sensors).` : `- \u{1F680} ZPD ADVANCED CHALLENGE (LESSON #${lessonIdx}):
-  \u2022 Focus on architectural edge cases, algorithmic optimization, and synthesis of learned concepts up to Lesson #${lessonIdx}.`;
+      const zpdCeilingRule = `- \u{1F3AF} CURRICULUM HORIZON ALLOWED SPACE & BOUNDARY MANDATE:
+  \u2022 SCOPE LOCK: All extension challenges MUST be 100% solvable using ONLY items from the student's Mastered Vocabulary and Current Lesson Scope.
+  \u2022 STRICTLY FORBIDDEN: NEVER introduce unintroduced APIs or mechanisms from upcoming lessons (No complex event buses, No remote network/API calls, No persistent databases, No async concurrency, No out-of-scope hardware/sensors unless explicitly part of the allowed toolkit).`;
       return `
 ### \u{1F680} EXTENSION CHALLENGE ARCHITECTURE INVARIANTS:
 ${zpdCeilingRule}