@thanh01.pmt/curriculum-kit 1.4.23 → 1.4.25

package/dist/index.cjs

@@ -1336,6 +1336,10 @@ function parseLessonFlow(lessonMarkdown) {
   }
   const durMatch = lessonMarkdown.match(/Estimated Duration:\s*([^\n]+)/i);
   if (durMatch) result.estimatedDuration = durMatch[1].trim();
+  if (!result.lessonTitle) {
+    const h1 = lessonMarkdown.match(/^#\s+(?:LESSON[^:]*:\s*)?(.+)$/m);
+    if (h1 && h1[1]) result.lessonTitle = h1[1].replace(/\*+/g, "").trim();
+  }
   const contractMatch = lessonMarkdown.match(/SLIDE must visualize:?\s*([^\n]+)/i);
   if (contractMatch) result.slideContract = contractMatch[1].trim();
   const actSeqSectionMatch = lessonMarkdown.match(/###\s*(?:\d+\.\s*)?Activity Sequence[\s\S]*?(?=(?:###|\n##\s+|$))/i);
@@ -1417,7 +1421,7 @@ var init_lessonFlowParser = __esm({
 
 // src/ai/prompts/slideBlueprintPrompt.ts
 function buildSlideBlueprintPrompt(params) {
-  const { lessonFlow, targetSlideCount, stylePresetName = "Blue Professional" } = params;
+  const { lessonFlow, targetSlideCount, stylePresetName = "Blue Professional", productSpecBlock } = params;
   const activitiesSummary = lessonFlow.activities.map(
     (a) => `Seq ${a.seq} [${a.phase}]: ${a.purpose} (Teacher: ${a.teacherMove} | Student: ${a.studentAction} | Time: ${a.time})`
   ).join("\n");
@@ -1439,7 +1443,9 @@ ${countGuidance}
 - Target Duration: ${lessonFlow.estimatedDuration}
 - Active Visual Style: "${stylePresetName}"
 ${lessonFlow.slideContract ? `- Slide Artifact Contract: "${lessonFlow.slideContract}"` : ""}
-
+${productSpecBlock ? `
+${productSpecBlock}
+` : ""}
 ### \u{1F5FA}\uFE0F CANONICAL ACTIVITY SEQUENCE:
 ${activitiesSummary || "Standard phased sequence"}
 
@@ -1513,7 +1519,7 @@ function buildSlideBatchPrompt(params) {
     skillPrompt,
     language = "Vietnamese",
     languageDirective = "",
-    headingDirective = "",
+    // deprecated — see interface doc
     groundContext = ""
   } = params;
   const slidesSpec = clusterSlides.map((s) => `
@@ -1534,7 +1540,6 @@ ${groundContext}
 ---` : ""}
 ### OPERATIONAL GROUND RULES FOR CHUNK GENERATION:
 ${languageDirective}
-${headingDirective}
 1. **FOCUS ON CLUSTER ${clusterId}: "${clusterTitle}"**:
    Generate EXACTLY the ${clusterSlides.length} slides requested in the user prompt.
 2. **ZERO ABBREVIATION / NO "// TODO"**:
@@ -1725,7 +1730,7 @@ async function inferStructured(schema, systemPrompt, userPrompt, options, label)
     const messages = [
       { role: "user", content: [systemPrompt, userPrompt].filter(Boolean).join("\n\n") }
     ];
-    const raw = await runCurriculumAIInference(messages, options.satelliteContext || "", options.runnerOptions, (token, type) => {
+    const raw = await runCurriculumAIInference(messages, "", options.runnerOptions, (token, type) => {
       if (type === "usage") options.onProgress?.("@illustrator", token, { type: "usage" });
     });
     const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
@@ -1911,7 +1916,8 @@ async function executeSlideProductionWorkflow(options) {
   const blueprintPrompt = buildSlideBlueprintPrompt({
     lessonFlow,
     targetSlideCount,
-    stylePresetName: stylePreset?.name || "Blue Professional"
+    stylePresetName: stylePreset?.name || "Blue Professional",
+    productSpecBlock: options.productSpecBlock
   });
   let blueprintItems;
   let allGeneratedSlides;
@@ -1994,7 +2000,6 @@ ${p.content}`).join("\n\n") : lessonFlow.rawContent.slice(0, 3500);
         skillPrompt,
         language,
         languageDirective,
-        headingDirective,
         groundContext: options.groundContext
       });
       try {
@@ -11719,19 +11724,30 @@ function extractToolchainFacts(refPack) {
   const factLines = [];
   for (const rawLine of excerpt.split("\n")) {
     const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-    if (/\d{1,2}(?:\.\d{1,2})?/.test(line) || /Xcode|Swift|macOS|iOS|SDK|Node|Python|JDK|\.NET/i.test(line)) {
-      factLines.push(line.replace(/^[-*•]\s*/, "- "));
-    }
+    if (!line || line.startsWith("#") || line.startsWith("<!--")) continue;
+    if (!/\d{1,2}(?:\.\d{1,2})?/.test(line) && !/Xcode|Swift|macOS|iOS|SDK|Node|Python|JDK|\.NET/i.test(line)) continue;
+    factLines.push(line.replace(/^[*\-•]\s*/, "- "));
     if (factLines.length >= 8) break;
   }
   return factLines;
 }
+function derivePrimaryTechnology(facts, briefing) {
+  const explicit = (briefing?.coreTechnology || briefing?.techStack || "").trim();
+  if (explicit && explicit.length <= 80) return explicit;
+  const found = [];
+  const CANON = ["Swift", "SwiftUI", "macOS", "iOS", "Xcode", "SwiftData", "Node.js", "TypeScript", "Python", "React"];
+  for (const name of CANON) {
+    if (facts.some((f) => f.includes(name)) && !found.includes(name)) found.push(name);
+  }
+  if (found.length > 0) return found.slice(0, 4).join(" + ");
+  const topic = (briefing?.topic || "").trim();
+  return topic && topic.length <= 60 ? topic : "";
+}
 function buildProductSpecBlock(input) {
   const b = input.briefing || {};
-  const platform = (input.overrides?.primaryLanguage || b.coreTechnology || b.techStack || b.topic || "").trim();
-  const hardware = (b.hardwarePlatform || b.studentEquipment || b.classDynamic || "").trim();
   const toolchainFacts = input.refPack ? extractToolchainFacts(input.refPack) : [];
+  const platform = (input.overrides?.primaryLanguage || derivePrimaryTechnology(toolchainFacts, b) || "").trim();
+  const hardware = (b.hardwarePlatform || b.studentEquipment || b.classDynamic || "").trim();
   const lines = [];
   lines.push("[PRODUCT SPEC \u2014 CANONICAL, BINDING FOR EVERY ARTIFACT OF THIS PROJECT]:");
   lines.push("All decisions below are PROJECT-WIDE. Every artifact (LESSON, satellites, KX)");
@@ -11747,7 +11763,7 @@ function buildProductSpecBlock(input) {
   if (input.overrides?.deliverableTemplate) {
     lines.push(`- Deliverable template: ${input.overrides.deliverableTemplate}`);
   }
-  if (toolchainFacts.length > 0) {
+  if (toolchainFacts.length > 0 && !input.skipToolchainList) {
     lines.push("- Toolchain & versions (ground truth):");
     for (const f of toolchainFacts) lines.push(`  ${f}`);
   }
@@ -11875,7 +11891,9 @@ async function ensureKnowledgeExposition(options) {
   const productSpecBlock = buildProductSpecBlock({
     refPack,
     briefing: techStack || hardwarePlatform ? { techStack, hardwarePlatform } : void 0,
-    overrides: options.productSpec
+    overrides: options.productSpec,
+    skipToolchainList: true
+    // same RefPack excerpt already in [GROUND TRUTH]
   });
   const originalUserPrompt = buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown, refPack) + (productSpecBlock ? "\n\n" + productSpecBlock : "");
   const content = (await llmFn(
@@ -11975,17 +11993,28 @@ async function ensureExpositionForLesson(storage, projectId, lessonCode, options
       const lpRaw = await storage.readSotDocument(projectId, "LEARNER_PROFILE.md");
       if (lpRaw) {
         const hwPatterns = [
+          // "Cơ sở phần cứng (Hardware Ecosystem): Học sinh thực hành trên máy..."
+          // — the audit: the old pattern captured the parenthetical label
+          // "(Hardware Ecosystem):" itself. Capture AFTER the closing paren + colon.
+          /\([^)]*Ecosystem[^)]*\)\s*:\s*([^\n\r]+)/i,
           /(?:Student Equipment|Hardware|Platform|Thiết bị|Thiết bị học tập)\s*(?:\(|:|\*)*\s*([^\n\r]+?)(?:\s*\*\*|[.).]?\s*$)/i,
           /(?:máy|device|machine)\s+([^,.;\n]{4,60}(?:M\d|Intel|PC|computer|mini)[^,.;\n]{0,30})/i
         ];
         for (const p of hwPatterns) {
           const m = lpRaw.match(p);
-          if (m && !hw) {
-            hw = m[1].trim();
+          if (m && m[1] && !hw) {
+            hw = m[1].trim().replace(/\*+/g, "").slice(0, 300);
             break;
           }
         }
       }
+      if (!hw) {
+        const rpRaw = await storage.readSotDocument(projectId, "REFERENCE_PACK.md");
+        if (rpRaw) {
+          const rp = rpRaw.match(/(?:School Lab|Thiết bị lớp học)[^\n]*\*\*([^*]+(?:M\d|Mac)[^*]*)\*\*/i);
+          if (rp && rp[1]) hw = rp[1].trim();
+        }
+      }
     } catch {
     }
   }
@@ -12722,11 +12751,11 @@ function buildSessionSliceContext(plan, lessonCode) {
   lines.push("- Time split: knowledge " + s.knowledge_minutes + "m / practice " + s.practice_minutes + "m / overhead " + s.overhead_minutes + "m");
   lines.push("- Depth assignments: " + s.depth_assignments.map((d) => d.node_id + "=" + d.depth.toUpperCase() + "(" + d.source + ")").join("; "));
   if (s.prerequisite_decisions.length > 0) {
-    lines.push("- Prerequisite decisions [7]:");
+    lines.push("- Prerequisite decisions [" + s.prerequisite_decisions.length + "]:");
     for (const d of s.prerequisite_decisions) lines.push("  * " + d.node_id + ": " + d.decision + " \u2014 " + d.reason);
   }
   if (s.scaffold_decisions.length > 0) {
-    lines.push("- Scaffold decisions [7]:");
+    lines.push("- Scaffold decisions [" + s.scaffold_decisions.length + "]:");
     for (const d of s.scaffold_decisions) lines.push("  * " + d.item + ": " + d.decision + (d.minutes_saved > 0 ? " (saves " + d.minutes_saved + "m)" : "") + " \u2014 " + d.reason);
   }
   lines.push("- Exit evidence: " + s.exit_evidence.join("; "));
@@ -25961,8 +25990,11 @@ function buildFrameworkExcerptForLesson(framework, lessonId) {
   });
   const rowIdx = scopeRows[0] ?? -1;
   const currentRow = rowIdx >= 0 ? lines[rowIdx] : "";
-  const prevRow = rowIdx > 0 && (lines[rowIdx - 1] || "").trim().startsWith("|") ? lines[rowIdx - 1] : "";
-  const nextRow = (lines[rowIdx + 1] || "").trim().startsWith("|") ? lines[rowIdx + 1] : "";
+  const isSeparatorRow = (l) => !!l && /^\s*\|?[\s:|-]+\|?\s*$/.test(l) && l.includes("-");
+  const prevRaw = rowIdx > 0 ? lines[rowIdx - 1] : "";
+  const prevRow = prevRaw.trim().startsWith("|") && !isSeparatorRow(prevRaw) ? prevRaw : "";
+  const nextRaw = lines[rowIdx + 1] || "";
+  const nextRow = nextRaw.trim().startsWith("|") && !isSeparatorRow(nextRaw) ? nextRaw : "";
   const hierStart = lines.findIndex((l) => /Structural Hierarchy/i.test(l));
   let hierarchyBlock = "";
   if (hierStart >= 0) {
@@ -26203,7 +26235,22 @@ async function produceSingleLesson(storage, projectId, lessonId, options = {}) {
   const framework = await storage.readSotDocument(projectId, "CURRICULUM_FRAMEWORK.md") || "";
   const styleGuide = await storage.readSotDocument(projectId, "CONTENT_STYLE_GUIDE.md") || "";
   const refPack = await storage.readSotDocument(projectId, "REFERENCE_PACK.md") || "";
+  let currentPlanHash;
+  try {
+    const planRaw0 = await storage.readArtifact(projectId, "_sot/CURRICULUM_PLAN.json");
+    if (planRaw0) currentPlanHash = JSON.parse(planRaw0).plan_hash;
+  } catch {
+  }
   await storage.readSotDocument(projectId, "LEARNER_PROFILE.md") || "";
+  const isStaleVsPlan = (content) => {
+    if (!content || !currentPlanHash) return false;
+    const m = content.match(/plan_hash:\s*"([0-9a-f]+)"/);
+    return !!m && m[1] !== currentPlanHash;
+  };
+  const stampPlanHash = (content) => {
+    if (!currentPlanHash || content.includes('plan_hash: "' + currentPlanHash + '"')) return content;
+    return content + '\n---\nplan_hash: "' + currentPlanHash + '"\n- **Plan reference:** ' + currentPlanHash + "\n";
+  };
   const slcMarkdown = options.sectionLanguageContract || await storage.readSotDocument(projectId, "SECTION_LANGUAGE_CONTRACT.md") || "";
   let targetLang = options.targetLanguage;
   if (!targetLang) {
@@ -26353,6 +26400,7 @@ ${renderHorizonPromptBlock(horizon)}`;
   } catch (hErr) {
     console.warn(`[produceSingleLesson] Notice: Curriculum Horizon extraction:`, hErr?.message || hErr);
   }
+  let productSpecBlock = "";
   const buildGroundTruthBlock = () => {
     const parts = [];
     if (expositionContext) {
@@ -26363,9 +26411,9 @@ ${expositionContext}`);
       parts.push(`### REFERENCE PACK GROUND TRUTH
 ${effectiveRefPack}`);
     }
-    const productSpec = buildProductSpecBlock({ refPack, briefing: options.briefing });
-    if (productSpec) {
-      parts.push(productSpec);
+    productSpecBlock = buildProductSpecBlock({ refPack, briefing: options.briefing, skipToolchainList: true });
+    if (productSpecBlock) {
+      parts.push(productSpecBlock);
     }
     return parts.length > 0 ? `
 
@@ -26382,10 +26430,17 @@ ${standardsContext}` : "";
   const sessionSliceBlock = sessionSliceContext ? `
 
 ${sessionSliceContext}` : "";
+  const platformGuardrail = buildDomainLexiconGuardrail(
+    options.briefing?.techStack || options.briefing?.coreTechnology,
+    options.briefing?.hardwarePlatform
+  );
+  const guardrailBlock = `
+
+${platformGuardrail}`;
   const assembleCommonContext = (sg) => `${baseContextPrefix}
 
 [CONTENT STYLE GUIDE EXCERPT]:
-${sg}${standardsBlock}${glossaryBlock}${buildGroundTruthBlock()}${sessionSliceBlock}${horizonBlock}`;
+${sg}${standardsBlock}${glossaryBlock}${buildGroundTruthBlock()}${sessionSliceBlock}${horizonBlock}${guardrailBlock}`;
   let commonContext = assembleCommonContext(effectiveStyleGuide);
   const MAX_COMPOSITE_PROMPT_CHARS = 3e4;
   const runnerOptions = options.customInference ? { customInference: options.customInference } : {};
@@ -26414,7 +26469,10 @@ ${sg}${standardsBlock}${glossaryBlock}${buildGroundTruthBlock()}${sessionSliceBl
   const lessonRelPath = `_content/${unitCode}/LESSON_${lessonCode}.md`;
   const existingLessonContent = await storage.readArtifact(projectId, lessonRelPath);
   let lessonContent = existingLessonContent || "";
-  if (artifactScope.includes("LESSON") && (!existingLessonContent || force)) {
+  if (artifactScope.includes("LESSON") && (!existingLessonContent || force || isStaleVsPlan(existingLessonContent))) {
+    if (existingLessonContent && !force && isStaleVsPlan(existingLessonContent)) {
+      onProgress?.("@content", `[STALENESS] LESSON_${lessonCode} was generated under a different plan_hash \u2014 regenerating against the current plan.`);
+    }
     onProgress?.("@content", `[1/4] Authoring Master Lesson Plan (${pedagogyLabel}): \`LESSON_${lessonCode}.md\` (${lessonTitle})...`);
     const dateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const mediaDirective = options.mediaPolicy && options.mediaPolicy.maxGenImagesPerArtifact > 0 ? `
@@ -26485,7 +26543,7 @@ Fix ALL issues above and output the complete corrected document.` }],
     } else {
       lessonContent = lintReport.autoFixedContent || rawLesson;
     }
-    await storage.saveArtifact(projectId, lessonRelPath, lessonContent);
+    await storage.saveArtifact(projectId, lessonRelPath, stampPlanHash(lessonContent));
     producedArtifacts.push(`LESSON_${lessonCode}.md`);
   }
   const contentHash = lessonContent ? computeContentHash(lessonContent) : void 0;
@@ -26830,7 +26888,8 @@ ${lessonExcerpt}${symbolLedgerBlock}`;
     });
   };
   const actRelPath = `_content/${unitCode}/ACT_${lessonCode}.md`;
-  if (artifactScope.includes("ACT") && (!await storage.readArtifact(projectId, actRelPath) || force)) {
+  const existingAct = await storage.readArtifact(projectId, actRelPath);
+  if (artifactScope.includes("ACT") && (!existingAct || force || isStaleVsPlan(existingAct))) {
     onProgress?.("@activity", `[2/4] Authoring Hands-on Lab: \`ACT_${lessonCode}.md\`...`);
     const actDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const actPrompt = `You are @activity (Lead Hands-on STEM & Laboratory Exercise Designer).
@@ -26890,7 +26949,7 @@ ${buildHeadingDirective("ACT", slcMarkdown, targetLang)}`;
         rawError: rawAct || "Empty AI response"
       });
     }
-    await storage.saveArtifact(projectId, actRelPath, rawAct);
+    await storage.saveArtifact(projectId, actRelPath, stampPlanHash(rawAct));
     await storage.updateArtifactState(projectId, lessonCode, "ACT", {
       state: "completed",
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -26900,12 +26959,18 @@ ${buildHeadingDirective("ACT", slcMarkdown, targetLang)}`;
     await judgeSat("ACT", rawAct);
   }
   const quizRelPath = `_content/${unitCode}/QUIZ_${lessonCode}.md`;
-  if (artifactScope.includes("QUIZ") && (!await storage.readArtifact(projectId, quizRelPath) || force)) {
+  const existingQuiz = await storage.readArtifact(projectId, quizRelPath);
+  if (artifactScope.includes("QUIZ") && (!existingQuiz || force || isStaleVsPlan(existingQuiz))) {
     onProgress?.("@assessor", `[3/4] Authoring Assessment Bank: \`QUIZ_${lessonCode}.md\`...`);
     const quizDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const quizPrompt = `You are @assessor (Lead Psychometrician & Competency Assessment Specialist).
 Based on Master Lesson Plan \`LESSON_${lessonCode}.md\`, author the scenario-based diagnostic question bank: \`QUIZ_${lessonCode}.md\`.
 
+SCOPE & PACING (prompt audit S-6):
+- This is a FORMATIVE CHECKPOINT for ONE 90-minute session, NOT an exam bank.
+- Size the bank to fit the session's Wrap-up (~10 minutes of answering): the MCQ bank, code-tracing question, and rubric together must be completable by a student in that time.
+- Question ONLY concepts inside this session's scope (see SESSION SLICE + ALLOWED DESIGN SPACE in the context).
+
 Mandatory Format Requirements:
 1. EXACT YAML Frontmatter \u2014 copy verbatim, then fill in the blanks:
 ---
@@ -26954,7 +27019,7 @@ ${buildHeadingDirective("QUIZ", slcMarkdown, targetLang)}`;
         rawError: rawQuiz || "Empty AI response"
       });
     }
-    await storage.saveArtifact(projectId, quizRelPath, rawQuiz);
+    await storage.saveArtifact(projectId, quizRelPath, stampPlanHash(rawQuiz));
     await storage.updateArtifactState(projectId, lessonCode, "QUIZ", {
       state: "completed",
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -26964,7 +27029,8 @@ ${buildHeadingDirective("QUIZ", slcMarkdown, targetLang)}`;
     await judgeSat("QUIZ", rawQuiz);
   }
   const slideRelPath = `_content/${unitCode}/SLIDE_${lessonCode}.md`;
-  if (artifactScope.includes("SLIDE") && (!await storage.readArtifact(projectId, slideRelPath) || force)) {
+  const existingSlide = await storage.readArtifact(projectId, slideRelPath);
+  if (artifactScope.includes("SLIDE") && (!existingSlide || force || isStaleVsPlan(existingSlide))) {
     onProgress?.("@illustrator", `[4/4] Authoring Presentation Slide Deck: \`SLIDE_${lessonCode}.md\`...`);
     const isHtmlEngine = options.slidesEngine !== "marp";
     if (isHtmlEngine) {
@@ -26989,6 +27055,7 @@ ${buildHeadingDirective("QUIZ", slcMarkdown, targetLang)}`;
         languageDirective,
         headingDirective: buildHeadingDirective("SLIDE", slcMarkdown, targetLang),
         groundContext: slideGroundContext,
+        productSpecBlock: productSpecBlock || void 0,
         satelliteContext,
         runnerOptions,
         onProgress: (agent, msg, meta) => {
@@ -26998,7 +27065,7 @@ ${buildHeadingDirective("QUIZ", slcMarkdown, targetLang)}`;
       let deckJson = workflowResult.deckJson;
       const markdownWrapper = workflowResult.markdownWrapper;
       let validation = presentationKitAi?.validateHtmlSlideDeck ? presentationKitAi.validateHtmlSlideDeck(deckJson, true) : deckJson && Array.isArray(deckJson.slides) ? { valid: true, score: 95, issues: [], slideCount: deckJson.slides.length} : { valid: false, score: 0, issues: [{ message: "Malformed JSON slide deck" }]};
-      await storage.saveArtifact(projectId, slideRelPath, markdownWrapper);
+      await storage.saveArtifact(projectId, slideRelPath, stampPlanHash(markdownWrapper));
       producedArtifacts.push(`SLIDE_${lessonCode}.md`);
       if (deckJson) {
         const deckJsonStr = JSON.stringify(deckJson, null, 2);
@@ -27089,7 +27156,7 @@ footer: "Curriculum OS \u2022 ${lessonCode} (${pedagogyLabel})"
           rawError: rawSlide || "Empty AI response"
         });
       }
-      await storage.saveArtifact(projectId, slideRelPath, rawSlide);
+      await storage.saveArtifact(projectId, slideRelPath, stampPlanHash(rawSlide));
       await storage.updateArtifactState(projectId, lessonCode, "SLIDE", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -27100,7 +27167,8 @@ footer: "Curriculum OS \u2022 ${lessonCode} (${pedagogyLabel})"
     }
   }
   const guideRelPath = `_content/${unitCode}/GUIDE_${lessonCode}.md`;
-  if (artifactScope.includes("GUIDE") && (!await storage.readArtifact(projectId, guideRelPath) || force)) {
+  const existingGuide = await storage.readArtifact(projectId, guideRelPath);
+  if (artifactScope.includes("GUIDE") && (!existingGuide || force || isStaleVsPlan(existingGuide))) {
     onProgress?.("@content", `Authoring Teacher Guide: \`GUIDE_${lessonCode}.md\`...`, { artifactType: "GUIDE" });
     const guideDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const guidePrompt = `You are @content (Senior Curriculum Developer & Teacher Facilitation Specialist).
@@ -27140,7 +27208,7 @@ ${buildHeadingDirective("GUIDE", slcMarkdown, targetLang)}`;
       }
     );
     if (rawGuide && !rawGuide.startsWith("\u26A0\uFE0F") && rawGuide.length >= 200) {
-      await storage.saveArtifact(projectId, guideRelPath, rawGuide);
+      await storage.saveArtifact(projectId, guideRelPath, stampPlanHash(rawGuide));
       await storage.updateArtifactState(projectId, lessonCode, "GUIDE", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -27151,7 +27219,8 @@ ${buildHeadingDirective("GUIDE", slcMarkdown, targetLang)}`;
     }
   }
   const handoutRelPath = `_content/${unitCode}/HANDOUT_${lessonCode}.md`;
-  if (artifactScope.includes("HANDOUT") && (!await storage.readArtifact(projectId, handoutRelPath) || force)) {
+  const existingHandout = await storage.readArtifact(projectId, handoutRelPath);
+  if (artifactScope.includes("HANDOUT") && (!existingHandout || force || isStaleVsPlan(existingHandout))) {
     onProgress?.("@content", `Authoring Student Handout: \`HANDOUT_${lessonCode}.md\`...`, { artifactType: "HANDOUT" });
     const handoutDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const handoutPrompt = `You are @content (Educational Content Specialist).
@@ -27191,7 +27260,7 @@ ${buildHeadingDirective("HANDOUT", slcMarkdown, targetLang)}`;
       }
     );
     if (rawHandout && !rawHandout.startsWith("\u26A0\uFE0F") && rawHandout.length >= 200) {
-      await storage.saveArtifact(projectId, handoutRelPath, rawHandout);
+      await storage.saveArtifact(projectId, handoutRelPath, stampPlanHash(rawHandout));
       await storage.updateArtifactState(projectId, lessonCode, "HANDOUT", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -27202,7 +27271,8 @@ ${buildHeadingDirective("HANDOUT", slcMarkdown, targetLang)}`;
     }
   }
   const wksRelPath = `_content/${unitCode}/WKS_${lessonCode}.md`;
-  if (artifactScope.includes("WKS") && (!await storage.readArtifact(projectId, wksRelPath) || force)) {
+  const existingWks = await storage.readArtifact(projectId, wksRelPath);
+  if (artifactScope.includes("WKS") && (!existingWks || force || isStaleVsPlan(existingWks))) {
     onProgress?.("@content", `Authoring Student Worksheet: \`WKS_${lessonCode}.md\`...`, { artifactType: "WKS" });
     const wksDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const wksPrompt = `You are @content (Instructional Activity & Worksheet Designer).
@@ -27246,7 +27316,7 @@ ${buildHeadingDirective("WKS", slcMarkdown, targetLang)}`;
       }
     );
     if (rawWks && !rawWks.startsWith("\u26A0\uFE0F") && rawWks.length >= 200) {
-      await storage.saveArtifact(projectId, wksRelPath, rawWks);
+      await storage.saveArtifact(projectId, wksRelPath, stampPlanHash(rawWks));
       await storage.updateArtifactState(projectId, lessonCode, "WKS", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -27257,7 +27327,8 @@ ${buildHeadingDirective("WKS", slcMarkdown, targetLang)}`;
     }
   }
   const codeRelPath = `_content/${unitCode}/CODE_${lessonCode}.md`;
-  if ((artifactScope.includes("CODE") || artifactScope.includes("CODE_LAB")) && (!await storage.readArtifact(projectId, codeRelPath) || force)) {
+  const existingCode = await storage.readArtifact(projectId, codeRelPath);
+  if ((artifactScope.includes("CODE") || artifactScope.includes("CODE_LAB")) && (!existingCode || force || isStaleVsPlan(existingCode))) {
     onProgress?.("@activity", `Authoring Executable Code Lab: \`CODE_${lessonCode}.md\`...`, { artifactType: "CODE" });
     const codeDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const codePrompt = `You are @activity & @tech_sme (Lead Software Engineer & Technical SME).
@@ -27305,7 +27376,7 @@ ${buildHeadingDirective("CODE", slcMarkdown, targetLang)}`;
       }
     );
     if (rawCode && !rawCode.startsWith("\u26A0\uFE0F") && rawCode.length >= 200) {
-      await storage.saveArtifact(projectId, codeRelPath, rawCode);
+      await storage.saveArtifact(projectId, codeRelPath, stampPlanHash(rawCode));
       await storage.updateArtifactState(projectId, lessonCode, "CODE", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -27321,7 +27392,8 @@ ${buildHeadingDirective("CODE", slcMarkdown, targetLang)}`;
     }
   }
   const extRelPath = `_content/${unitCode}/EXT_${lessonCode}.md`;
-  if (artifactScope.includes("EXT") && (!await storage.readArtifact(projectId, extRelPath) || force)) {
+  const existingExt = await storage.readArtifact(projectId, extRelPath);
+  if (artifactScope.includes("EXT") && (!existingExt || force || isStaleVsPlan(existingExt))) {
     onProgress?.("@activity", `Authoring Advanced Extension Challenge: \`EXT_${lessonCode}.md\`...`, { artifactType: "EXT" });
     const extDateStr = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const isVi = targetLang === "vi";
@@ -27391,7 +27463,7 @@ ${buildHeadingDirective("EXT", slcMarkdown, targetLang)}`;
       }
     );
     if (rawExt && !rawExt.startsWith("\u26A0\uFE0F") && rawExt.length >= 200) {
-      await storage.saveArtifact(projectId, extRelPath, rawExt);
+      await storage.saveArtifact(projectId, extRelPath, stampPlanHash(rawExt));
       await storage.updateArtifactState(projectId, lessonCode, "EXT", {
         state: "completed",
         generatedAt: (/* @__PURE__ */ new Date()).toISOString(),