@thanh01.pmt/curriculum-kit 1.4.22 → 1.4.24

package/dist/index.d.cts

@@ -165,6 +165,20 @@ interface ProduceLessonOptions {
         mode?: 'search_only' | 'gen_only' | 'auto';
     };
     approvedArtifacts?: string[];
+    /**
+     * 5-Whys RC-canonicality: project briefing feeding the canonical PRODUCT_SPEC
+     * block (platform, hardware, deliverable template). Injected identically into
+     * every artifact's ground truth so no artifact re-decides product shape.
+     */
+    briefing?: {
+        techStack?: string;
+        coreTechnology?: string;
+        topic?: string;
+        hardwarePlatform?: string;
+        studentEquipment?: string;
+        classDynamic?: string;
+        language?: string;
+    };
     /**
      * P46 RC2: host-provided inference override (Vercel AI SDK gateway).
      * When supplied, ALL lesson/satellite LLM calls route through it — the kit's
@@ -658,6 +672,12 @@ interface GenerateExpositionOptions {
     /** REFERENCE_PACK.md raw content — technical ground truth (versions, APIs).
      *  5-Whys RC-vacuum: without it the KX model regresses to pretrained facts. */
     refPack?: string;
+    /** 5-Whys RC-canonicality: canonical PRODUCT_SPEC fields so KX does not
+     *  re-decide the deliverable shape that LESSON/satellites already share. */
+    productSpec?: {
+        deliverableTemplate?: string;
+        primaryLanguage?: string;
+    };
 }
 interface ExpositionResult {
     relPath: string;

package/dist/index.d.ts

@@ -165,6 +165,20 @@ interface ProduceLessonOptions {
         mode?: 'search_only' | 'gen_only' | 'auto';
     };
     approvedArtifacts?: string[];
+    /**
+     * 5-Whys RC-canonicality: project briefing feeding the canonical PRODUCT_SPEC
+     * block (platform, hardware, deliverable template). Injected identically into
+     * every artifact's ground truth so no artifact re-decides product shape.
+     */
+    briefing?: {
+        techStack?: string;
+        coreTechnology?: string;
+        topic?: string;
+        hardwarePlatform?: string;
+        studentEquipment?: string;
+        classDynamic?: string;
+        language?: string;
+    };
     /**
      * P46 RC2: host-provided inference override (Vercel AI SDK gateway).
      * When supplied, ALL lesson/satellite LLM calls route through it — the kit's
@@ -658,6 +672,12 @@ interface GenerateExpositionOptions {
     /** REFERENCE_PACK.md raw content — technical ground truth (versions, APIs).
      *  5-Whys RC-vacuum: without it the KX model regresses to pretrained facts. */
     refPack?: string;
+    /** 5-Whys RC-canonicality: canonical PRODUCT_SPEC fields so KX does not
+     *  re-decide the deliverable shape that LESSON/satellites already share. */
+    productSpec?: {
+        deliverableTemplate?: string;
+        primaryLanguage?: string;
+    };
 }
 interface ExpositionResult {
     relPath: string;

package/dist/index.mjs

@@ -11612,6 +11612,137 @@ function extractSymbolLedger(lessonMarkdown) {
   return result;
 }
 
+// src/services/artifactValidators.ts
+var CJK_RE = /[\u3400-\u4DBF\u4E00-\u9FFF\u3040-\u30FF\uAC00-\uD7AF]/g;
+function scanCjkLeaks(content) {
+  const matches = content.match(CJK_RE);
+  if (!matches || matches.length === 0) return null;
+  const lines = [];
+  for (const line of content.split("\n")) {
+    if (CJK_RE.test(line)) lines.push(line.trim().slice(0, 160));
+  }
+  return {
+    code: "cjk-leak",
+    detail: `Ph\xE1t hi\u1EC7n ${matches.length} k\xFD t\u1EF1 CJK (Trung/Nh\u1EADt/H\xE0n) trong artifact ng\xF4n ng\u1EEF Vi\u1EC7t/Anh. B\u1ECB c\u1EA5m tuy\u1EC7t \u0111\u1ED1i.`,
+    evidence: lines.slice(0, 5)
+  };
+}
+var VERSION_CLAIM_RE = /\b([A-Z][A-Za-z+#.\-]{1,24})\s+(\d{1,2}(?:\.\d{1,2})?)\b/g;
+function checkVersionGroundTruth(content, refPack) {
+  if (!refPack || !refPack.trim()) return null;
+  const packLower = refPack.toLowerCase();
+  const claims = /* @__PURE__ */ new Map();
+  for (const m of content.matchAll(VERSION_CLAIM_RE)) {
+    const tool = m[1];
+    if (claims.size === 0 || !claims.has(tool)) claims.set(tool, m[2]);
+  }
+  const contradictions = [];
+  for (const [tool, claimed] of claims) {
+    const toolRe = new RegExp(`\\b${tool.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+(\\d{1,2}(?:\\.\\d{1,2})?)\\b`, "i");
+    const packMatch = packLower.match(toolRe);
+    if (packMatch && packMatch[1] !== claimed) {
+      contradictions.push(`${tool}: artifact n\xF3i ${claimed}, REFERENCE_PACK ch\u1ED1t ${packMatch[1]}`);
+    }
+  }
+  if (contradictions.length === 0) return null;
+  return {
+    code: "version-contradiction",
+    detail: `Version m\xE2u thu\u1EABn v\u1EDBi ground truth REFERENCE_PACK: ${contradictions.join("; ")}. S\u1EEDa theo b\u1EA3n trong REFERENCE_PACK.`,
+    evidence: contradictions
+  };
+}
+function checkScopeDrift(content, scopedKeywords, tolerance = 0) {
+  const conceptHeaders = /* @__PURE__ */ new Set();
+  for (const m of content.matchAll(/\*\*([^*\n]{3,60}?)\s*\((?:WHAT|CIO|SIO|ULO)[^)]*\):\*\*/g)) {
+    conceptHeaders.add(m[1].toLowerCase());
+  }
+  if (conceptHeaders.size === 0) return null;
+  const drift = [];
+  for (const header of conceptHeaders) {
+    const hit = scopedKeywords.some((kw) => {
+      const k = kw.toLowerCase().trim();
+      if (!k) return false;
+      const tokens = k.split(/\s+/);
+      const present = tokens.filter((t) => header.includes(t)).length;
+      return present >= Math.max(1, tokens.length - tolerance);
+    });
+    if (!hit) drift.push(header);
+  }
+  if (drift.length === 0) return null;
+  return {
+    code: "scope-drift",
+    detail: `C\xE1c kh\xE1i ni\u1EC7m sau KH\xD4NG thu\u1ED9c scope c\u1EE7a bu\u1ED5i h\u1ECDc (kh\xF4ng c\xF3 trong new_keywords/graph node keywords): ${drift.join(" | ")}. Xo\xE1 ho\xE0n to\xE0n ho\u1EB7c thay b\u1EB1ng kh\xE1i ni\u1EC7m trong scope.`,
+    evidence: drift
+  };
+}
+function validateArtifactDeterministic(input) {
+  const issues = [];
+  const cjk = scanCjkLeaks(input.content);
+  if (cjk) issues.push(cjk);
+  if (input.refPack) {
+    const ver = checkVersionGroundTruth(input.content, input.refPack);
+    if (ver) issues.push(ver);
+  }
+  if (input.scopedKeywords && input.scopedKeywords.length > 0) {
+    const scope = checkScopeDrift(input.content, input.scopedKeywords);
+    if (scope) issues.push(scope);
+  }
+  return { ok: issues.length === 0, issues };
+}
+function validatorRepairPrompt(issues) {
+  return [
+    "DETERMINISTIC VALIDATOR FAILURES (mechanically detected \u2014 non-negotiable, fix ALL):",
+    ...issues.map((i, n) => `${n + 1}. [${i.code}] ${i.detail}${i.evidence.length ? `
+   Evidence: ${i.evidence.join(" | ").slice(0, 400)}` : ""}`)
+  ].join("\n");
+}
+
+// src/services/productSpec.ts
+function extractToolchainFacts(refPack) {
+  const { excerpt } = buildSectionAwareExcerpt(refPack, {
+    priorities: ["Technical Overview & Architecture Blueprint", "Hardware Pinout & Wiring Configuration Matrix"],
+    budget: 4e3
+  });
+  if (!excerpt) return [];
+  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 (factLines.length >= 8) break;
+  }
+  return factLines;
+}
+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 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)");
+  lines.push("must describe the SAME product. Contradicting or re-deciding any line here is a");
+  lines.push("consistency failure \u2014 if a needed decision is absent, stay GENERIC, never invent.");
+  lines.push("");
+  if (platform) {
+    lines.push(`- Primary technology: ${platform}`);
+  }
+  if (hardware) {
+    lines.push(`- Hardware / classroom setup: ${hardware}`);
+  }
+  if (input.overrides?.deliverableTemplate) {
+    lines.push(`- Deliverable template: ${input.overrides.deliverableTemplate}`);
+  }
+  if (toolchainFacts.length > 0) {
+    lines.push("- Toolchain & versions (ground truth):");
+    for (const f of toolchainFacts) lines.push(`  ${f}`);
+  }
+  if (lines.length <= 5) return "";
+  return lines.join("\n");
+}
+
 // src/services/knowledgeExpositionService.ts
 var EXPOSITION_REL = (lessonCode) => "_sot/expositions/" + lessonCode + ".md";
 var ExpositionApprovalError = class extends Error {
@@ -11729,7 +11860,12 @@ async function ensureKnowledgeExposition(options) {
   }
   const targetLanguage = options.targetLanguage || plan.translation?.target_language || "vi";
   const originalSystemPrompt = buildSystemPrompt(targetLanguage, techStack, hardwarePlatform);
-  const originalUserPrompt = buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown, refPack);
+  const productSpecBlock = buildProductSpecBlock({
+    refPack,
+    briefing: techStack || hardwarePlatform ? { techStack, hardwarePlatform } : void 0,
+    overrides: options.productSpec
+  });
+  const originalUserPrompt = buildUserPrompt(session, plan, glossary, targetLanguage, options.slcMarkdown, refPack) + (productSpecBlock ? "\n\n" + productSpecBlock : "");
   const content = (await llmFn(
     originalSystemPrompt,
     originalUserPrompt
@@ -11763,7 +11899,17 @@ async function ensureKnowledgeExposition(options) {
       const parsed = JSON.parse(match[0]);
       return { verdict: parsed.verdict ?? "NEEDS_REVISION", score: parsed.score ?? 0, critique: parsed.critique ?? "" };
     };
-    let verdict = await judgeOnce(finalContent);
+    const scopedKeywords = [
+      ...session.new_keywords,
+      ...glossary.map((g) => g.term)
+    ];
+    const runDeterministic = (candidate) => validateArtifactDeterministic({
+      content: candidate,
+      refPack,
+      scopedKeywords
+    });
+    let det = runDeterministic(finalContent);
+    let verdict = det.ok ? await judgeOnce(finalContent) : { verdict: "NEEDS_REVISION", score: 0, critique: validatorRepairPrompt(det.issues) };
     if (verdict.verdict !== "APPROVED") {
       const repairPrompt = [
         originalUserPrompt,
@@ -11771,11 +11917,12 @@ async function ensureKnowledgeExposition(options) {
         "--- YOUR PREVIOUS DRAFT (REJECTED, fix ALL issues below) ---",
         finalContent,
         "",
-        "--- JUDGE CRITIQUE (fix ALL issues, output the COMPLETE corrected document) ---",
+        "--- CRITIQUE (fix ALL issues, output the COMPLETE corrected document) ---",
         verdict.critique
       ].join("\n");
       finalContent = (await llmFn(originalSystemPrompt, repairPrompt)).trim();
-      verdict = await judgeOnce(finalContent);
+      det = runDeterministic(finalContent);
+      verdict = det.ok ? await judgeOnce(finalContent) : { verdict: "NEEDS_REVISION", score: 0, critique: validatorRepairPrompt(det.issues) };
     }
     if (verdict.verdict !== "APPROVED") {
       throw new Error("EXPOSITION failed judge for " + lessonCode + " (verdict " + verdict.verdict + ", score " + verdict.score + "): " + verdict.critique);
@@ -26044,7 +26191,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) {
@@ -26204,6 +26366,10 @@ ${expositionContext}`);
       parts.push(`### REFERENCE PACK GROUND TRUTH
 ${effectiveRefPack}`);
     }
+    const productSpec = buildProductSpecBlock({ refPack, briefing: options.briefing });
+    if (productSpec) {
+      parts.push(productSpec);
+    }
     return parts.length > 0 ? `
 
 [GROUND TRUTH]:
@@ -26251,7 +26417,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 ? `
@@ -26322,7 +26491,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;
@@ -26362,6 +26531,23 @@ ${yamlBlock.trim()}
 `);
       };
       var injectYamlReviewMetadata = injectYamlReviewMetadata2;
+      const lessonDet = validateArtifactDeterministic({ content: lessonContent, refPack });
+      if (!lessonDet.ok) {
+        const detCritique = validatorRepairPrompt(lessonDet.issues);
+        onProgress?.("@reviewer", `\u26D4 LESSON deterministic validator FAIL: ${detCritique.slice(0, 200)}`);
+        await storage.updateArtifactState(projectId, lessonCode, "LESSON", {
+          state: "rejected",
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          contentHash: computeContentHash(lessonContent),
+          review: {
+            decision: "NEEDS_REVISION",
+            reviewedBy: "@heuristic-linter",
+            reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            score: 0,
+            critique: detCritique
+          }
+        });
+      }
       const judgeObjectives = parseLessonObjectives(lessonContent, concept, bloomLevel);
       const judgeExpositionExcerpt = expositionContext ? buildExpositionExcerpt(expositionContext, { budget: 3e3, sectionLanguageContract: slcMarkdown, artifactType: "KNOWLEDGE_EXPOSITION" }).excerpt : void 0;
       const judgeResult = await LLMJudgeEngine.evaluateArtifactWithLLM({
@@ -26617,6 +26803,23 @@ ${currentContent}` }],
 ${lessonExcerpt}${symbolLedgerBlock}`;
   const judgeSat = (sat, content) => {
     if (gateModeFor(gates, sat) !== "LLM_JUDGE") return Promise.resolve();
+    const det = validateArtifactDeterministic({ content, refPack });
+    if (!det.ok) {
+      const critique = validatorRepairPrompt(det.issues);
+      onProgress?.("@reviewer", `\u26D4 ${sat} deterministic validator FAIL: ${critique.slice(0, 200)}`);
+      return storage.updateArtifactState(projectId, lessonCode, sat, {
+        state: "rejected",
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        contentHash: computeContentHash(content),
+        review: {
+          decision: "NEEDS_REVISION",
+          reviewedBy: "@heuristic-linter",
+          reviewedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          score: 0,
+          critique
+        }
+      });
+    }
     return judgeSatelliteArtifact({
       storage,
       projectId,
@@ -26633,7 +26836,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).
@@ -26693,7 +26897,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(),
@@ -26703,7 +26907,8 @@ ${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).
@@ -26757,7 +26962,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(),
@@ -26767,7 +26972,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) {
@@ -26801,7 +27007,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);
@@ -26892,7 +27098,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(),
@@ -26903,7 +27109,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).
@@ -26943,7 +27150,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(),
@@ -26954,7 +27161,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).
@@ -26994,7 +27202,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(),
@@ -27005,7 +27213,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).
@@ -27049,7 +27258,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(),
@@ -27060,7 +27269,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).
@@ -27108,7 +27318,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(),
@@ -27124,7 +27334,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";
@@ -27194,7 +27405,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(),