@namewta/speculo 0.8.13 → 1.0.1

package/template/workflows/learning/common/tools/validate-learning.mjs

@@ -1,356 +1,254 @@
 #!/usr/bin/env node
 
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-} from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const CHANGE_NAME = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const DOMAIN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const WORK_ID = /^learning\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const CHANGE_STATUS = new Set(["active", "blocked", "awaiting_retention", "completed", "archived"]);
-const PHASE = new Set(["intake", "assessment", "teaching", "practice", "immediate_quiz", "retention", "ready_to_archive", "archived"]);
-const DOMAIN_TYPE = new Set(["project", "product", "subject", "language", "skill"]);
-const RESULT = new Set(["not_attempted", "failed", "passed", "needs_review"]);
-const KNOWLEDGE_STATUS = new Set(["mastered", "review_due", "needs_refresh", "superseded"]);
-const EXPECTED_WORKS = new Set([
-  "A-archive-and-consolidate",
-  "A-assess-and-plan",
-  "E-eli5",
-  "I-init-setup",
-  "P-practice",
-  "Q-quiz",
-  "R-review",
-]);
-
-function parseArgs(argv) {
+const LOCATOR = /^(?:changes\/.+|archive\/[0-9]{4}-[0-9]{2}\/.+)$/;
+const EXPECTED_WORKS = new Set(["A-archive", "A-assess-and-plan", "C-consolidate", "H-homework", "I-init-setup", "L-lesson", "R-review"]);
+const OLD_WORKS = new Set(["A-archive-and-consolidate", "E-eli5", "P-practice", "Q-quiz"]);
+const PHASE = new Set(["planning", "teaching", "homework", "review", "consolidating", "closed", "archived"]);
+const LIFECYCLE = new Set(["active", "blocked", "closed", "archived"]);
+const EVIDENCE = new Set(["not_attempted", "passed", "needs_review"]);
+
+function options(argv) {
   const result = { workflowRoot: null, stateRoot: null, stage: null, change: null, selfCheck: false };
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === "--workflow-root") result.workflowRoot = resolve(argv[++index] ?? "");
-    else if (arg === "--state-root") result.stateRoot = resolve(argv[++index] ?? "");
-    else if (arg === "--stage") result.stage = argv[++index] ?? null;
-    else if (arg === "--change") result.change = argv[++index] ?? null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--workflow-root") result.workflowRoot = resolve(argv[++i] ?? "");
+    else if (arg === "--state-root") result.stateRoot = resolve(argv[++i] ?? "");
+    else if (arg === "--stage") result.stage = argv[++i] ?? null;
+    else if (arg === "--change") result.change = argv[++i] ?? null;
     else if (arg === "--self-check") result.selfCheck = true;
     else throw new Error(`unknown option: ${arg}`);
   }
-  if (!result.workflowRoot && !result.stateRoot && !result.selfCheck) {
-    throw new Error("use --workflow-root <path>, --state-root <path>, or --self-check");
-  }
-  if (result.stage && !new Set(["pre-archive", "complete"]).has(result.stage)) {
-    throw new Error("--stage must be pre-archive or complete");
-  }
+  if (!result.workflowRoot && !result.stateRoot && !result.selfCheck) throw new Error("use --workflow-root, --state-root, or --self-check");
+  if (result.stage && !new Set(["pre-archive", "complete"]).has(result.stage)) throw new Error("--stage must be pre-archive or complete");
   if (result.stage && !result.change) throw new Error("--stage requires --change");
   if (result.change && !CHANGE_NAME.test(result.change)) throw new Error("--change has an invalid name");
   return result;
 }
 
-function isFile(path) {
-  return existsSync(path) && statSync(path).isFile();
-}
-
-function isDirectory(path) {
-  return existsSync(path) && statSync(path).isDirectory();
-}
-
+function isFile(path) { return existsSync(path) && statSync(path).isFile(); }
+function isDir(path) { return existsSync(path) && statSync(path).isDirectory(); }
 function readJson(path, label, errors) {
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch (error) {
-    errors.push(`${label}: invalid JSON (${error.message})`);
-    return null;
-  }
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { errors.push(`${label}: invalid JSON (${error.message})`); return null; }
 }
-
-function walk(root) {
-  if (!isDirectory(root)) return [];
-  const files = [];
+function files(root) {
+  if (!isDir(root)) return [];
+  const result = [];
   for (const entry of readdirSync(root, { withFileTypes: true })) {
     const path = join(root, entry.name);
-    if (entry.isDirectory()) files.push(...walk(path));
-    else if (entry.isFile()) files.push(path);
+    if (entry.isDirectory()) result.push(...files(path));
+    else if (entry.isFile()) result.push(path);
   }
-  return files;
-}
-
-function sameMembers(actual, expected) {
-  return actual.size === expected.size && [...actual].every((item) => expected.has(item));
+  return result;
 }
-
 function duplicates(values) {
   const seen = new Set();
   return values.filter((value) => seen.has(value) || !seen.add(value));
 }
-
-function validDateTime(value) {
-  return typeof value === "string" && !Number.isNaN(Date.parse(value));
+function validDate(value) { return typeof value === "string" && !Number.isNaN(Date.parse(value)); }
+function frontmatter(text) {
+  const match = /^---\s*\n([\s\S]*?)\n---\s*/.exec(text);
+  const result = {};
+  if (!match) return result;
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (!field) continue;
+    const value = field[2].trim();
+    if (/^\[.*\]$/.test(value)) result[field[1]] = value.slice(1, -1).split(",").map((item) => item.trim()).filter(Boolean);
+    else if (/^\d+$/.test(value)) result[field[1]] = Number(value);
+    else result[field[1]] = value.replace(/^['"]|['"]$/g, "");
+  }
+  return result;
 }
 
 function validateWorkflowRoot(root, errors) {
-  const indexPath = join(root, "INDEX.md");
-  const readmePath = join(root, "README.md");
-  const seedPath = join(root, "_state", "status.json");
-  const runtimePath = join(root, "runtime-contract.json");
-  for (const path of [indexPath, readmePath, seedPath, runtimePath]) {
-    if (!isFile(path)) errors.push(`${path}: required workflow file is missing`);
-  }
-  if (errors.length) return;
-
-  const index = readFileSync(indexPath, "utf8");
-  const readme = readFileSync(readmePath, "utf8");
-  if (!/^id: learning$/m.test(index) || !/^type: workflow$/m.test(index) || !/^workflow: learning$/m.test(index)) {
-    errors.push("INDEX.md: identity must be learning/type workflow");
-  }
-  for (const heading of ["## 永久知识", "## Work 激活"]) {
-    if (!index.includes(heading)) errors.push(`INDEX.md: missing ${heading}`);
-  }
-  if (!index.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push("INDEX.md: missing activation pointer");
-  if ((readme.match(/AUTO-INDEX-START/g) ?? []).length !== 1 || (readme.match(/AUTO-INDEX-END/g) ?? []).length !== 1) {
-    errors.push("README.md: requires one AUTO-INDEX marker pair");
-  }
-
-  const works = new Set(readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && /^[A-Z]-/.test(entry.name))
-    .map((entry) => entry.name));
-  if (!sameMembers(works, EXPECTED_WORKS)) {
-    errors.push(`workflow works mismatch: expected ${[...EXPECTED_WORKS].sort().join(", ")}; found ${[...works].sort().join(", ")}`);
-  }
+  const required = ["INDEX.md", "README.md", "_state/status.json", "runtime-contract.json"];
+  for (const file of required) if (!isFile(join(root, file))) errors.push(`${file}: required workflow file is missing`);
+  if (!isFile(join(root, "README.md"))) return;
+  const index = readFileSync(join(root, "INDEX.md"), "utf8");
+  const readme = readFileSync(join(root, "README.md"), "utf8");
+  if (!/^id: learning$/m.test(index) || !/^type: workflow$/m.test(index) || !/^workflow: learning$/m.test(index)) errors.push("INDEX.md: invalid identity");
+  if (!(index.includes("## 主题知识") || index.includes("## 永久知识")) || !index.includes("## Work 激活") || !index.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push("INDEX.md: missing passive/activation sections");
+  if ((readme.match(/AUTO-INDEX-START/g) ?? []).length !== 1 || (readme.match(/AUTO-INDEX-END/g) ?? []).length !== 1) errors.push("README.md: requires one AUTO-INDEX marker pair");
+  const works = new Set(readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && /^[A-Z]-/.test(entry.name) && isFile(join(root, entry.name, `${entry.name}.md`))).map((entry) => entry.name));
+  if (works.size !== EXPECTED_WORKS.size || [...EXPECTED_WORKS].some((work) => !works.has(work))) errors.push(`workflow works mismatch: expected ${[...EXPECTED_WORKS].sort().join(", ")}; found ${[...works].sort().join(", ")}`);
+  for (const old of OLD_WORKS) if (isDir(join(root, old)) && files(join(root, old)).length) errors.push(`${old}: obsolete v1 work is still shipped`);
   for (const work of works) {
-    const path = join(root, work, `${work}.md`);
-    if (!isFile(path)) {
-      errors.push(`${work}: missing same-named entry`);
-      continue;
-    }
-    const text = readFileSync(path, "utf8");
+    const text = readFileSync(join(root, work, `${work}.md`), "utf8");
     if (!text.includes("<Path>{roots.workflows}/learning/README.md</Path>")) errors.push(`${work}: missing activation contract reference`);
     if (!/^workflow: learning$/m.test(text) || !/^type: workflow-entry$/m.test(text)) errors.push(`${work}: invalid frontmatter identity`);
   }
-
-  const seed = readJson(seedPath, "_state/status.json", errors);
-  if (seed && (seed.schema_version !== 1 || seed.workflow !== "learning" || !Array.isArray(seed.active) || !Array.isArray(seed.archived))) {
-    errors.push("_state/status.json: expected empty learning schema v1 status");
-  }
-  const runtime = readJson(runtimePath, "runtime-contract.json", errors);
-  if (runtime && (runtime.schema_version !== 1 || runtime.workflow !== "learning" || runtime.config !== null || runtime.opaque_default !== "preserve-byte-for-byte")) {
-    errors.push("runtime-contract.json: invalid learning contract");
-  }
-  for (const schema of ["status.schema.json", "change-status.schema.json"]) {
-    readJson(join(root, "common", "schemas", schema), `common/schemas/${schema}`, errors);
-  }
-
-  for (const path of walk(root).filter((candidate) => candidate.toLowerCase().endsWith(".md"))) {
-    if (/```mermaid\b/i.test(readFileSync(path, "utf8"))) {
-      errors.push(`${relative(root, path)}: Learning diagrams must use fenced ASCII text, not Mermaid`);
-    }
-  }
-
-  const teachingContracts = [
-    [join(root, "E-eli5", "E-eli5.md"), ["5 岁的小孩", "大一新生", "ASCII", "不得生成 Mermaid"]],
-    [join(root, "E-eli5", "lesson-template.md"), ["## 教学表达基线", "5 岁的小孩", "大一新生", "```text"]],
-    [join(root, "common", "rules", "teaching-policy.md"), ["5 岁的小孩", "大一新生", "默认使用", "纯文本 ASCII"]],
-    [join(root, "I-init-setup", "learner-profile-template.md"), ["教学表达基线", "5 岁的小孩", "仅纯文本 ASCII"]],
+  const seed = readJson(join(root, "_state/status.json"), "_state/status.json", errors);
+  if (seed && (seed.schema_version !== 2 || seed.workflow !== "learning" || !Array.isArray(seed.active) || !Array.isArray(seed.archived))) errors.push("_state/status.json: expected empty learning schema v2 status");
+  const runtime = readJson(join(root, "runtime-contract.json"), "runtime-contract.json", errors);
+  if (runtime && (runtime.schema_version !== 1 || runtime.workflow !== "learning" || runtime.config !== null || runtime.opaque_default !== "preserve-byte-for-byte" || !runtime.structured_state.includes(".speculo/learning/changes/**/.status.json"))) errors.push("runtime-contract.json: missing recursive v2 paths");
+  for (const schema of ["status.schema.json", "change-status.schema.json"]) readJson(join(root, "common", "schemas", schema), `common/schemas/${schema}`, errors);
+  const contracts = [
+    ["L-lesson/L-lesson.md", ["30–40", "estimated_minutes", "time_budget", "ELI5"]],
+    ["L-lesson/lesson-template.md", ["lesson_id", "source_ids", "反例与边界", "文字等价物"]],
+    ["H-homework/H-homework.md", ["Submission: ready", "Explain (English)"]],
+    ["H-homework/homework-template.md", ["Q1", "A1", "Submission: pending"]],
+    ["common/rules/teaching-policy.md", ["coverage_depth", "不以字符数"]],
   ];
-  for (const [path, requiredMarkers] of teachingContracts) {
-    if (!isFile(path)) {
-      errors.push(`${relative(root, path)}: required teaching contract is missing`);
-      continue;
-    }
+  for (const [file, markers] of contracts) {
+    const path = join(root, file);
+    if (!isFile(path)) { errors.push(`${file}: required contract is missing`); continue; }
     const text = readFileSync(path, "utf8");
-    for (const marker of requiredMarkers) {
-      if (!text.includes(marker)) errors.push(`${relative(root, path)}: missing '${marker}'`);
-    }
+    for (const marker of markers) if (!text.includes(marker)) errors.push(`${file}: missing '${marker}'`);
   }
 }
 
-function validateGlobalStatus(status, errors) {
-  if (!status) return;
-  if (status.schema_version !== 1 || status.workflow !== "learning" || !Array.isArray(status.active) || !Array.isArray(status.archived)) {
-    errors.push("status.json: expected learning schema v1 with active and archived arrays");
-    return;
-  }
-  const activeNames = [];
-  for (const [index, entry] of status.active.entries()) {
-    const label = `status.json active[${index}]`;
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-      errors.push(`${label}: must be an object`);
-      continue;
-    }
-    if (!CHANGE_NAME.test(entry.change ?? "")) errors.push(`${label}: invalid change`);
-    if (!DOMAIN.test(entry.domain ?? "")) errors.push(`${label}: invalid domain`);
-    if (typeof entry.topic !== "string" || !entry.topic.trim()) errors.push(`${label}: topic is required`);
-    if (!(entry.current_work === null || WORK_ID.test(entry.current_work ?? ""))) errors.push(`${label}: invalid current_work`);
-    if (!Array.isArray(entry.works_run) || entry.works_run.some((item) => !WORK_ID.test(item)) || duplicates(entry.works_run ?? []).length) {
-      errors.push(`${label}: works_run must contain unique learning work ids`);
-    }
-    activeNames.push(entry.change);
-  }
-  if (duplicates(activeNames).length || duplicates(status.archived).length) errors.push("status.json: duplicate change names");
-  for (const name of status.archived) {
-    if (!CHANGE_NAME.test(name)) errors.push(`status.json: invalid archived change ${name}`);
-    if (activeNames.includes(name)) errors.push(`status.json: ${name} is both active and archived`);
-  }
+function validateEntry(entry, label, errors, archived) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) { errors.push(`${label}: must be an object`); return null; }
+  for (const key of ["change_id", "kind", "domain", "topic_id", "locator", "parent_change", "root_change", "current_work", "works_run"]) if (!(key in entry)) errors.push(`${label}: missing ${key}`);
+  if (!CHANGE_NAME.test(entry.change_id ?? "") || !["learning", "consolidation"].includes(entry.kind) || !DOMAIN.test(entry.domain ?? "") || !DOMAIN.test(entry.topic_id ?? "")) errors.push(`${label}: invalid identity`);
+  if (!LOCATOR.test(entry.locator ?? "") || String(entry.locator).split("/").includes("..")) errors.push(`${label}: invalid locator`);
+  if (!(entry.parent_change === null || CHANGE_NAME.test(entry.parent_change ?? "")) || !CHANGE_NAME.test(entry.root_change ?? "")) errors.push(`${label}: invalid parent/root`);
+  if (!(entry.current_work === null || WORK_ID.test(entry.current_work ?? ""))) errors.push(`${label}: invalid current_work`);
+  if (!Array.isArray(entry.works_run) || entry.works_run.some((item) => !WORK_ID.test(item)) || duplicates(entry.works_run).length) errors.push(`${label}: invalid works_run`);
+  if (entry.updated_at !== undefined && !validDate(entry.updated_at)) errors.push(`${label}: invalid updated_at`);
+  if (archived && !String(entry.locator).startsWith("archive/")) errors.push(`${label}: archived entry must use archive locator`);
+  if (!archived && String(entry.locator).startsWith("archive/")) errors.push(`${label}: active entry cannot use archive locator`);
+  return entry;
 }
 
-function validateMasteryGate(changeStatus, label, errors) {
-  const mastery = changeStatus.mastery;
-  if (!mastery || typeof mastery !== "object" || Array.isArray(mastery)) {
-    errors.push(`${label}: mastery is required`);
-    return;
-  }
-  if (!RESULT.has(mastery.immediate) || !RESULT.has(mastery.retention)) errors.push(`${label}: invalid mastery result`);
-  if (mastery.score !== null && (typeof mastery.score !== "number" || mastery.score < 0 || mastery.score > 100)) errors.push(`${label}: invalid mastery score`);
-  if (typeof mastery.critical_objectives_passed !== "boolean" || typeof mastery.transfer_passed !== "boolean") errors.push(`${label}: mastery booleans are required`);
+function validateMastery(value, label, errors) {
+  const mastery = value.mastery;
+  if (!mastery || typeof mastery !== "object") { errors.push(`${label}: mastery is required`); return; }
+  if (!["unverified", "immediate", "retention_verified"].includes(mastery.overall) || !EVIDENCE.has(mastery.immediate) || !["not_scheduled", "due", "passed", "needs_review"].includes(mastery.retention) || !EVIDENCE.has(mastery.critical_objectives) || !EVIDENCE.has(mastery.transfer)) errors.push(`${label}: invalid mastery projection`);
+  if (mastery.overall === "retention_verified" && mastery.retention !== "passed") errors.push(`${label}: retention_verified requires retention passed`);
   if (!Array.isArray(mastery.blocking_misconceptions) || !Array.isArray(mastery.evidence)) errors.push(`${label}: mastery arrays are required`);
-  if (!(mastery.next_review_at === null || validDateTime(mastery.next_review_at))) errors.push(`${label}: invalid next_review_at`);
-
-  if (changeStatus.change_status === "awaiting_retention" && mastery.immediate !== "passed") {
-    errors.push(`${label}: awaiting_retention requires immediate passed`);
-  }
-  if (["completed", "archived"].includes(changeStatus.change_status)) {
-    if (mastery.immediate !== "passed" || mastery.retention !== "passed") errors.push(`${label}: completed knowledge requires both mastery gates passed`);
-    if (typeof mastery.score !== "number" || mastery.score < 80) errors.push(`${label}: completed knowledge requires score >= 80`);
-    if (!mastery.critical_objectives_passed) errors.push(`${label}: completed knowledge requires all critical objectives`);
-    if (!mastery.transfer_passed) errors.push(`${label}: completed knowledge requires transfer evidence`);
-    if (mastery.blocking_misconceptions.length) errors.push(`${label}: completed knowledge has blocking misconceptions`);
-    if (mastery.evidence.length < 2 || !mastery.evidence.some((item) => /\/quiz\/immediate-/.test(item)) || !mastery.evidence.some((item) => /\/quiz\/retention-/.test(item))) {
-      errors.push(`${label}: completed knowledge requires immediate and retention result evidence`);
-    }
-  }
-}
-
-function validateChangeStatus(value, expectedName, expectedArchived, errors) {
-  const label = `${expectedName}/.status.json`;
-  if (!value) return;
-  if (value.schema_version !== 1 || value.artifact !== "learning-change-status") errors.push(`${label}: invalid identity/schema`);
-  if (value.change !== expectedName) errors.push(`${label}: change must match directory`);
-  if (!DOMAIN.test(value.domain ?? "") || !DOMAIN_TYPE.has(value.domain_type)) errors.push(`${label}: invalid domain or domain_type`);
-  if (typeof value.topic !== "string" || !value.topic.trim()) errors.push(`${label}: topic is required`);
-  if (!CHANGE_STATUS.has(value.change_status) || !PHASE.has(value.phase)) errors.push(`${label}: invalid status or phase`);
-  if (!(value.current_work === null || WORK_ID.test(value.current_work ?? ""))) errors.push(`${label}: invalid current_work`);
-  if (!Array.isArray(value.works_run) || value.works_run.some((item) => !WORK_ID.test(item)) || duplicates(value.works_run ?? []).length) errors.push(`${label}: invalid works_run`);
-  if (!validDateTime(value.created_at) || !validDateTime(value.updated_at)) errors.push(`${label}: created_at and updated_at must be date-times`);
-  if (!Array.isArray(value.blockers)) errors.push(`${label}: blockers must be an array`);
-  if (expectedArchived && (value.change_status !== "archived" || value.phase !== "archived" || !validDateTime(value.archived_at) || typeof value.archive_path !== "string")) {
-    errors.push(`${label}: archived index requires archived status, phase, time, and path`);
-  }
-  if (expectedArchived && value.archive_path !== `<Path>{roots.state}/learning/archive/${expectedName.slice(0, 7)}/${expectedName}</Path>`) {
-    errors.push(`${label}: archive_path does not match the indexed archive location`);
+  if (!(mastery.next_review_at === null || validDate(mastery.next_review_at))) errors.push(`${label}: invalid next_review_at`);
+}
+
+function validateChange(value, expectedId, expectedLocator, errors) {
+  const label = `${expectedId}/.status.json`;
+  if (!value || typeof value !== "object") return;
+  if (value.schema_version === 1) { errors.push(`${label}: learning-reset-required; v1 is not auto-migrated`); return; }
+  if (value.schema_version !== 2 || value.artifact !== "learning-change-status" || value.change_id !== expectedId || value.locator !== expectedLocator) errors.push(`${label}: invalid identity/schema/locator`);
+  if (!CHANGE_NAME.test(value.change_id ?? "") || !["learning", "consolidation"].includes(value.kind) || !DOMAIN.test(value.domain ?? "") || !DOMAIN.test(value.topic_id ?? "")) errors.push(`${label}: invalid domain/kind/topic`);
+  if (!LIFECYCLE.has(value.lifecycle) || !PHASE.has(value.phase)) errors.push(`${label}: invalid lifecycle/phase`);
+  if (!(value.current_work === null || WORK_ID.test(value.current_work ?? "")) || !Array.isArray(value.works_run) || duplicates(value.works_run).length) errors.push(`${label}: invalid work projection`);
+  if (!validDate(value.created_at) || !validDate(value.updated_at)) errors.push(`${label}: invalid timestamps`);
+  if (!(value.closed_at === null || validDate(value.closed_at)) || !(value.archived_at === null || validDate(value.archived_at))) errors.push(`${label}: invalid close/archive timestamp`);
+  if (value.lifecycle === "archived" && (value.phase !== "archived" || value.current_work !== null || !String(value.locator).startsWith("archive/"))) errors.push(`${label}: archive state does not match locator`);
+  if (value.lifecycle !== "archived" && (value.archived_at !== null || value.archive_path !== null || String(value.locator).startsWith("archive/"))) errors.push(`${label}: active state contains archive fields`);
+  if (!value.homework || !["none", "pending", "reviewed", "needs_revision"].includes(value.homework.status) || !(value.homework.latest_id === null || typeof value.homework.latest_id === "string")) errors.push(`${label}: invalid homework projection`);
+  if (!Array.isArray(value.children) || !Array.isArray(value.blockers)) errors.push(`${label}: children/blockers must be arrays`);
+  validateMastery(value, label, errors);
+}
+
+function validateLessons(changeRoot, errors) {
+  const lessonRoot = join(changeRoot, "lessons");
+  if (!isDir(lessonRoot)) return;
+  for (const path of files(lessonRoot).filter((candidate) => /\.md$/.test(candidate) && !candidate.endsWith("INDEX.md"))) {
+    const text = readFileSync(path, "utf8");
+    const label = relative(changeRoot, path).split(sep).join("/");
+    const meta = frontmatter(text);
+    if (!/^L-[0-9]{3}(?:-[a-z0-9-]+)?$/.test(String(meta.lesson_id ?? ""))) errors.push(`${label}: lesson_id is required`);
+    if (!Number.isInteger(meta.estimated_minutes) || meta.estimated_minutes < 30 || meta.estimated_minutes > 40) errors.push(`${label}: estimated_minutes must be 30–40`);
+    if (!Array.isArray(meta.time_budget) && !text.includes("time_budget:")) errors.push(`${label}: time_budget is required`);
+    for (const heading of ["宏观", "机制", "精确定义", "English", "正例", "反例", "迁移", "误区", "总结", "来源"]) if (!text.includes(heading)) errors.push(`${label}: missing teaching coverage '${heading}'`);
+    if (!/(文字等价物|完整的文字|文字替代)/.test(text)) errors.push(`${label}: visual representation needs a text equivalent`);
+    if (!/source_ids:|\| Source ID \|/.test(text)) errors.push(`${label}: source_ids/source table is required`);
+    if (/\bverdict\b|\bmastered\b|^##\s*(?:Answers|Review)/mi.test(text)) errors.push(`${label}: lesson must not contain homework review/mastery fields`);
+  }
+}
+
+function validateHomework(changeRoot, errors) {
+  const homeworkRoot = join(changeRoot, "homework");
+  if (!isDir(homeworkRoot)) return;
+  for (const path of files(homeworkRoot).filter((candidate) => /^HW-.*\.md$/.test(candidate.split(sep).pop() ?? ""))) {
+    const text = readFileSync(path, "utf8");
+    const label = relative(changeRoot, path).split(sep).join("/");
+    const ready = /(^|\n)Submission:\s*ready\s*(?:\n|$)/i.test(text);
+    const reviewed = /^##\s+Review\s*$/mi.test(text);
+    if (!/(^|\n)Submission:\s*(?:pending|ready)\s*(?:\n|$)/i.test(text)) errors.push(`${label}: Submission marker is required`);
+    const questions = [...text.matchAll(/^###\s+Q(\d+)\b/gm)].map((match) => Number(match[1]));
+    const answers = [...text.matchAll(/^###\s+A(\d+)\b/gm)].map((match) => Number(match[1]));
+    if (!questions.length || questions.length !== answers.length || questions.some((number, index) => number !== index + 1) || answers.some((number, index) => number !== index + 1)) errors.push(`${label}: Q/A numbering must be contiguous and paired`);
+    if (reviewed && !ready) errors.push(`${label}: review cannot exist before Submission: ready`);
+    if (reviewed && !/correct|partial|incorrect|uncertain/i.test(text) || reviewed && !/Explain \(English\)/.test(text)) errors.push(`${label}: review needs verdict and Explain (English)`);
   }
-  if (!expectedArchived && value.change_status === "archived") errors.push(`${label}: active index cannot point to archived change`);
-  if (value.change_status === "completed" && (!validDateTime(value.completed_at) || value.phase !== "ready_to_archive")) errors.push(`${label}: completed requires completed_at and ready_to_archive phase`);
-  validateMasteryGate(value, label, errors);
-}
-
-function statePathFromTag(stateRoot, taggedPath) {
-  const match = /^<Path>\{roots\.state\}\/learning\/(.+)<\/Path>$/.exec(taggedPath);
-  return match ? join(stateRoot, ...match[1].split("/")) : null;
 }
 
 function validateContext(stateRoot, errors) {
-  const contextRoot = join(stateRoot, "context");
-  if (!isDirectory(contextRoot)) return;
-  for (const required of ["INDEX.md", "REVIEW.md"]) {
-    if (!isFile(join(contextRoot, required))) errors.push(`context/${required}: missing`);
-  }
-  const ids = new Map();
-  for (const file of walk(contextRoot).filter((path) => path.endsWith(".md"))) {
-    const text = readFileSync(file, "utf8");
-    const fileLabel = relative(stateRoot, file).split(sep).join("/");
-    for (const match of text.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
-      const target = match[1].split("#")[0].trim();
-      if (!target || /^(?:https?:|mailto:|#)/.test(target) || target.includes("<")) continue;
-      const resolved = resolve(dirname(file), decodeURIComponent(target));
-      if (!resolved.startsWith(resolve(contextRoot) + sep) || !existsSync(resolved)) errors.push(`${fileLabel}: broken or escaping Markdown link ${target}`);
-    }
-    const id = /^\|\s*Knowledge ID\s*\|\s*([^|]+?)\s*\|\s*$/m.exec(text)?.[1];
-    if (!id) continue;
-    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) errors.push(`${fileLabel}: invalid Knowledge ID ${id}`);
-    if (ids.has(id)) errors.push(`${fileLabel}: duplicate Knowledge ID ${id} also in ${ids.get(id)}`);
-    else ids.set(id, fileLabel);
-    const state = /^\|\s*状态\s*\|\s*([^|]+?)\s*\|\s*$/m.exec(text)?.[1];
-    if (!KNOWLEDGE_STATUS.has(state)) errors.push(`${fileLabel}: invalid or missing knowledge 状态`);
-    for (const heading of ["## 当前理解", "## 心智模型", "## 示例与应用", "## 常见误区", "## 来源与证据"]) {
-      if (!text.includes(heading)) errors.push(`${fileLabel}: missing ${heading}`);
-    }
+  const context = join(stateRoot, "context");
+  if (!isDir(context)) return;
+  for (const required of ["INDEX.md", "REVIEW.md"]) if (!isFile(join(context, required))) errors.push(`context/${required}: missing`);
+  const ids = new Set();
+  for (const path of files(context).filter((candidate) => candidate.endsWith(".md"))) {
+    const text = readFileSync(path, "utf8");
+    const id = /^\|\s*topic_id\s*\|\s*([^|]+)\s*\|/mi.exec(text)?.[1]?.trim();
+    if (id) { if (ids.has(id)) errors.push(`${relative(context, path)}: duplicate topic_id ${id}`); ids.add(id); }
+    if (path.includes(`${sep}topics${sep}`) && !/provenance|source_change_id|claim_id/i.test(text)) errors.push(`${relative(context, path)}: topic view needs provenance`);
   }
 }
 
-function validateStateRoot(root, options, errors) {
+function validateStateRoot(root, opts, errors) {
   const statusPath = join(root, "status.json");
-  if (!isFile(statusPath)) {
-    errors.push("status.json: missing");
-    return;
-  }
+  if (!isFile(statusPath)) { errors.push("status.json: missing"); return; }
   const status = readJson(statusPath, "status.json", errors);
-  validateGlobalStatus(status, errors);
-  if (!status || !Array.isArray(status.active) || !Array.isArray(status.archived)) return;
-
-  for (const entry of status.active) {
-    if (!entry || typeof entry.change !== "string") continue;
-    const path = join(root, "changes", entry.change, ".status.json");
-    if (!isFile(path)) {
-      errors.push(`${entry.change}: indexed active change is missing .status.json`);
-      continue;
-    }
-    const changeStatus = readJson(path, `${entry.change}/.status.json`, errors);
-    validateChangeStatus(changeStatus, entry.change, false, errors);
-    if (changeStatus && (changeStatus.domain !== entry.domain || changeStatus.topic !== entry.topic || changeStatus.current_work !== entry.current_work || JSON.stringify(changeStatus.works_run) !== JSON.stringify(entry.works_run))) {
-      errors.push(`${entry.change}: global and change status projections differ`);
-    }
-    if (options.stage === "pre-archive" && (!options.change || options.change === entry.change) && changeStatus?.change_status !== "completed") {
-      errors.push(`${entry.change}: pre-archive requires completed status`);
-    }
-    if (options.stage === "complete" && (!options.change || options.change === entry.change)) {
-      errors.push(`${entry.change}: complete stage cannot leave the change active`);
-    }
-    for (const evidence of changeStatus?.mastery?.evidence ?? []) {
-      const resolved = statePathFromTag(root, evidence);
-      if (!resolved || !isFile(resolved)) errors.push(`${entry.change}: mastery evidence does not exist ${evidence}`);
-    }
-  }
-
-  for (const name of status.archived) {
-    const archiveRoot = join(root, "archive", name.slice(0, 7), name);
-    const path = join(archiveRoot, ".status.json");
-    if (!isFile(path)) {
-      errors.push(`${name}: indexed archive is missing .status.json`);
-      continue;
-    }
-    validateChangeStatus(readJson(path, `${name}/.status.json`, errors), name, true, errors);
-    if (isDirectory(join(root, "changes", name))) errors.push(`${name}: archived change still exists under changes`);
-    if (options.stage === "complete" && (!options.change || options.change === name) && !isFile(join(archiveRoot, "promotion-plan.md"))) {
-      errors.push(`${name}: complete stage requires archived promotion-plan.md`);
-    }
-  }
-  if (options.change && !status.active.some((entry) => entry.change === options.change) && !status.archived.includes(options.change)) errors.push(`${options.change}: change is not indexed`);
+  if (!status) return;
+  if (status.schema_version === 1) { errors.push("status.json: learning-reset-required; v1 is not auto-migrated"); return; }
+  if (status.schema_version !== 2 || status.workflow !== "learning" || !Array.isArray(status.active) || !Array.isArray(status.archived)) { errors.push("status.json: expected learning schema v2"); return; }
+  const active = status.active.map((entry, index) => validateEntry(entry, `status.active[${index}]`, errors, false)).filter(Boolean);
+  const archived = status.archived.map((entry, index) => validateEntry(entry, `status.archived[${index}]`, errors, true)).filter(Boolean);
+  const all = [...active, ...archived];
+  const ids = all.map((entry) => entry.change_id);
+  if (duplicates(ids).length) errors.push("status.json: duplicate or overlapping change ids");
+  const byId = new Map(all.map((entry) => [entry.change_id, entry]));
+  for (const entry of all) {
+    const path = join(root, ...String(entry.locator).split("/"), ".status.json");
+    if (!isFile(path)) { errors.push(`${entry.change_id}: indexed Change is missing ${path}`); continue; }
+    const value = readJson(path, `${entry.change_id}/.status.json`, errors);
+    validateChange(value, entry.change_id, entry.locator, errors);
+    if (value && (value.domain !== entry.domain || value.topic_id !== entry.topic_id || value.parent_change !== entry.parent_change || value.current_work !== entry.current_work || JSON.stringify(value.works_run) !== JSON.stringify(entry.works_run))) errors.push(`${entry.change_id}: global and change projections differ`);
+    const seen = new Set();
+    let parent = entry.parent_change;
+    while (parent !== null) {
+      if (seen.has(parent)) { errors.push(`${entry.change_id}: parent cycle detected`); break; }
+      seen.add(parent);
+      if (!byId.has(parent)) { errors.push(`${entry.change_id}: parent_change ${parent} is not indexed`); break; }
+      parent = byId.get(parent).parent_change;
+    }
+    const changeRoot = join(root, ...String(entry.locator).split("/"));
+    validateLessons(changeRoot, errors);
+    validateHomework(changeRoot, errors);
+    if (opts.stage === "pre-archive" && (!opts.change || opts.change === entry.change_id) && value?.lifecycle !== "closed") errors.push(`${entry.change_id}: pre-archive requires lifecycle closed`);
+    if (opts.stage === "complete" && (!opts.change || opts.change === entry.change_id) && !String(entry.locator).startsWith("archive/")) errors.push(`${entry.change_id}: complete stage requires archived locator`);
+  }
+  const locationsPath = join(root, "locations.json");
+  if (all.length && !isFile(locationsPath)) errors.push("locations.json: required when Changes exist");
+  if (isFile(locationsPath)) {
+    const locations = readJson(locationsPath, "locations.json", errors);
+    if (locations && (locations.schema_version !== 2 || locations.workflow !== "learning" || !Array.isArray(locations.entries))) errors.push("locations.json: expected schema v2");
+    else if (locations) {
+      const locationIds = locations.entries.map((entry) => entry.change_id);
+      if (duplicates(locationIds).length) errors.push("locations.json: duplicate change ids");
+      for (const entry of all) if (!locations.entries.some((candidate) => candidate.change_id === entry.change_id && candidate.locator === entry.locator)) errors.push(`${entry.change_id}: locations.json does not match current locator`);
+    }
+  }
+  if (opts.change && !all.some((entry) => entry.change_id === opts.change)) errors.push(`${opts.change}: Change is not indexed`);
   validateContext(root, errors);
 }
 
 function main() {
-  const options = parseArgs(process.argv.slice(2));
+  const opts = options(process.argv.slice(2));
   const errors = [];
-  if (options.selfCheck) {
-    const ownRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-    validateWorkflowRoot(ownRoot, errors);
-  }
-  if (options.workflowRoot) validateWorkflowRoot(options.workflowRoot, errors);
-  if (options.stateRoot) validateStateRoot(options.stateRoot, options, errors);
-  if (errors.length) {
-    console.error(`Learning validation failed (${errors.length})`);
-    for (const error of errors) console.error(`  - ${error}`);
-    process.exitCode = 1;
-    return;
-  }
+  if (opts.selfCheck) validateWorkflowRoot(resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."), errors);
+  if (opts.workflowRoot) validateWorkflowRoot(opts.workflowRoot, errors);
+  if (opts.stateRoot) validateStateRoot(opts.stateRoot, opts, errors);
+  if (errors.length) { console.error(`Learning validation failed (${errors.length})`); for (const error of errors) console.error(`  - ${error}`); process.exitCode = 1; return; }
   console.log("Learning validation: OK");
 }
 
-try {
-  main();
-} catch (error) {
-  console.error(`Learning validation failed: ${error.message}`);
-  process.exitCode = 1;
-}
+try { main(); } catch (error) { console.error(`Learning validation failed: ${error.message}`); process.exitCode = 1; }

package/template/workflows/learning/manifest.json

@@ -0,0 +1 @@
+{"schema_version":1,"id":"learning","version":"1.0.0","persistent_knowledge":["<Path>{roots.state}/learning/context/INDEX.md</Path>","<Path>{roots.state}/learning/context/REVIEW.md</Path>"],"stages":[{"id":"intake","after":[],"inputs":["goal"],"outputs":["course"],"risk":"read-only","context_budget":12000},{"id":"teach","after":["intake"],"inputs":["course"],"outputs":["lesson"],"risk":"read-only","context_budget":18000},{"id":"practice","after":["teach"],"inputs":["lesson"],"outputs":["homework"],"risk":"read-only","context_budget":12000},{"id":"review","after":["practice"],"inputs":["homework"],"outputs":["mastery"],"risk":"read-only","context_budget":12000},{"id":"consolidate","after":["review"],"inputs":["lesson","mastery"],"outputs":["knowledge"],"risk":"local-reversible","context_budget":14000}]}

package/template/workflows/learning/runtime-contract.json

@@ -4,8 +4,9 @@
   "config": null,
   "structured_state": [
     ".speculo/learning/status.json",
-    ".speculo/learning/changes/*/.status.json",
-    ".speculo/learning/archive/*/*/.status.json"
+    ".speculo/learning/locations.json",
+    ".speculo/learning/changes/**/.status.json",
+    ".speculo/learning/archive/**/.status.json"
   ],
   "opaque_default": "preserve-byte-for-byte"
 }

package/template/workflows/ops/manifest.json

@@ -0,0 +1 @@
+{"schema_version":1,"id":"ops","version":"1.0.0","persistent_knowledge":["<Path>{roots.state}/ops/context/</Path>","<Path>{roots.state}/ops/adr/</Path>","<Path>{roots.state}/ops/runbooks/</Path>","<Path>{roots.state}/ops/projects/{project_id}/context/</Path>","<Path>{roots.state}/ops/projects/{project_id}/adr/</Path>","<Path>{roots.state}/ops/projects/{project_id}/runbooks/</Path>"],"stages":[{"id":"intake","after":[],"inputs":["request","target"],"outputs":["dossier"],"risk":"read-only","context_budget":16000},{"id":"plan","after":["intake"],"inputs":["dossier"],"outputs":["plan","approval"],"risk":"external-mutation","context_budget":22000},{"id":"execute","after":["plan"],"inputs":["plan","approval"],"outputs":["attempt"],"risk":"production-critical","context_budget":20000},{"id":"verify","after":["execute"],"inputs":["attempt"],"outputs":["verification"],"risk":"read-only","context_budget":16000},{"id":"learn","after":["verify"],"inputs":["verification"],"outputs":["retrospective"],"risk":"local-reversible","context_budget":12000}]}

package/template/workflows/person/manifest.json

@@ -0,0 +1 @@
+{"schema_version":1,"id":"person","version":"1.0.0","persistent_knowledge":[],"stages":[{"id":"frame","after":[],"inputs":["question"],"outputs":["dossier"],"risk":"read-only","context_budget":14000},{"id":"deliberate","after":["frame"],"inputs":["dossier"],"outputs":["decision"],"risk":"read-only","context_budget":18000},{"id":"act","after":["deliberate"],"inputs":["decision"],"outputs":["actions"],"risk":"local-reversible","context_budget":10000}]}