@thanh01.pmt/curriculum-kit 1.4.22 → 1.4.23

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);
@@ -26204,6 +26351,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]:
@@ -26362,6 +26513,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 +26785,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,