@namewta/speculo 0.8.5 → 0.8.6

package/template/workflows/learning/common/schemas/status.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:learning:status:v1",
+  "title": "Learning Global Status",
+  "type": "object",
+  "required": ["schema_version", "workflow", "active", "archived"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "workflow": {"const": "learning"},
+    "active": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["change", "domain", "topic", "current_work", "works_run"],
+        "properties": {
+          "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+          "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+          "topic": {"type": "string", "minLength": 1},
+          "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
+          "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true}
+        },
+        "additionalProperties": false
+      }
+    },
+    "archived": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}

package/template/workflows/learning/common/skills/knowledge-promotion/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: knowledge-promotion
+description: 在 Learning 内按掌握证据规划或应用 Markdown 知识提升，并为周期复习更新当前知识状态和分层索引。
+---
+
+# Knowledge Promotion
+
+本 Skill 由 R-review 和 A-archive 调用，写入路径必须由调用方提供且位于 Learning context。默认 `plan-promotion` 只分析；任何 context 写入均需调用方获得用户对精确路径和动作的确认。
+
+## 模式
+
+- `plan-promotion`：读取 completed change 和现有索引，产生 create/merge/supersede/archive-only 计划。
+- `apply-promotion`：只执行已确认且重新验证无 drift 的计划。
+- `mark-review-state`：更新指定知识的 `mastered | review_due | needs_refresh`、最近验证、下次复习和 REVIEW 行。
+
+## Plan Promotion
+
+1. 验证即时/保持 result、关键目标、迁移、误区和 change 状态；任一门不满足返回 blocked。
+2. 每个通过 OBJ 形成一个候选 Knowledge ID。读取总目录、目标领域 INDEX 和精确同 id 文件；不得以全文相似搜索代替 id/索引判断。
+3. 无同 id 时 `create`；当前结论兼容时 `merge`；新证据推翻当前结论时 `supersede`；仅会话性内容 `archive-only`。
+4. 计划必须列出所有叶子、领域 overview/INDEX、总 INDEX、REVIEW 和证据链接变化，并把完整候选 Markdown 写入调用方 change 的 `promotion-staging/`。重复 id、断链或来源冲突标记 needs-confirmation；staging 不等于 context 写入。
+
+## Apply Promotion
+
+1. 重读计划涉及的全部文件并核对 drift；目标意外出现、内容 hash 变化或证据状态变化即停止。
+2. 在调用方 change 的 `promotion-rollback/` 为每个目标保存原 Markdown；原目标不存在时在 `rollback-manifest.md` 明确记录。快照完整前不写 context。
+3. 知识文件按 `<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/knowledge-template.md</Path>` 创建/合并；新领域同时使用 domain index 和 overview 模板。掌握证据指向即将形成的 archive 路径，只使用 `promotion-staging/` 中已确认的候选内容。
+4. 自叶到根更新领域 INDEX、总 INDEX 和 REVIEW。表格按稳定 Knowledge ID 排序，同一 id 只有一行。
+5. 重读所有链接并运行 Learning validator。任一失败按 manifest 逆序恢复：原文件覆盖回去，原本不存在的文件删除；恢复后再次验证。恢复成功前不得继续归档移动。
+
+## Mark Review State
+
+只修改调用方指定的知识文件和 REVIEW 行。失败标记 `needs_refresh`，通过更新 `mastered`、最近证据和下一日期；不删除或改写 archive，也不修改无关知识正文。
+
+## 完成标准
+
+- 没有 RAG、向量或隐式相似匹配；
+- 每个动作由双门证据和一个 Knowledge ID 支持；
+- 计划模式无写入，执行模式有明确确认和 drift 检查；
+- 更新后从总 INDEX 可以通过真实链接到达每个当前知识文件。
+
+## 模板引用
+
+- 知识正文：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/knowledge-template.md</Path>`
+- 领域目录：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/domain-index-template.md</Path>`
+- 领域概览：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/domain-overview-template.md</Path>`

package/template/workflows/learning/common/skills/knowledge-promotion/domain-index-template.md

@@ -0,0 +1,6 @@
+# <领域名称>目录
+
+> 本文件只保存导航和当前状态；具体知识读取链接目标。
+
+| Knowledge ID | 类型 | 状态 | 文件 | 前置知识 | 最近验证 | 下次复习 |
+| --- | --- | --- | --- | --- | --- | --- |

package/template/workflows/learning/common/skills/knowledge-promotion/domain-overview-template.md

@@ -0,0 +1,19 @@
+# <领域名称>概览
+
+| 字段 | 内容 |
+| --- | --- |
+| Domain ID | `<domain>` |
+| 类型 | `<project/product/subject/language/skill>` |
+| 入口 | `[领域目录](INDEX.md)` |
+
+## 我目前能做什么
+
+## 领域地图
+
+```text
++----------+     +------+     +------+
+| 基础概念 | --> | 方法 | --> | 应用 |
++----------+     +------+     +------+
+```
+
+## 当前边界与待学习内容

package/template/workflows/learning/common/skills/knowledge-promotion/knowledge-template.md

@@ -0,0 +1,25 @@
+# <知识标题>
+
+| 字段 | 内容 |
+| --- | --- |
+| Knowledge ID | `<domain>/<topic>` |
+| 状态 | `mastered` |
+| 前置知识 | `<相对 Markdown 链接或无>` |
+| 相关知识 | `<相对 Markdown 链接或无>` |
+| 掌握证据 | `<归档 change 内 result 路径>` |
+| 最近验证 | `YYYY-MM-DD` |
+| 下次复习 | `YYYY-MM-DD` |
+
+## 当前理解
+
+## 心智模型
+
+## 示例与应用
+
+## 常见误区
+
+## 来源与证据
+
+## 替代关系
+
+`<没有 supersedes 时写无>`

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

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+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 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;
+    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.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 readJson(path, label, errors) {
+  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 = [];
+  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);
+  }
+  return files;
+}
+
+function sameMembers(actual, expected) {
+  return actual.size === expected.size && [...actual].every((item) => expected.has(item));
+}
+
+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 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(", ")}`);
+  }
+  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");
+    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"]],
+  ];
+  for (const [path, requiredMarkers] of teachingContracts) {
+    if (!isFile(path)) {
+      errors.push(`${relative(root, path)}: required teaching 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}'`);
+    }
+  }
+}
+
+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 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`);
+  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 (!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}`);
+    }
+  }
+}
+
+function validateStateRoot(root, options, errors) {
+  const statusPath = join(root, "status.json");
+  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`);
+  validateContext(root, errors);
+}
+
+function main() {
+  const options = parseArgs(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;
+  }
+  console.log("Learning validation: OK");
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Learning validation failed: ${error.message}`);
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "workflow": "learning",
+  "config": null,
+  "structured_state": [
+    ".speculo/learning/status.json",
+    ".speculo/learning/changes/*/.status.json",
+    ".speculo/learning/archive/*/*/.status.json"
+  ],
+  "opaque_default": "preserve-byte-for-byte"
+}

package/template/workflows/specdev/INDEX.md

@@ -3,8 +3,8 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、零基础新生图解、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
-keywords: [specdev, local-first, 规格驱动开发, decision-complete, eli5, prototype, code-review, TDD, 证据]
+description: 以本地工件为唯一开发权威，从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 与知识归档。
+keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
 ---
 
 # SpecDev Index

package/template/workflows/specdev/README.md

@@ -18,7 +18,7 @@ SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责
         ↓
 Triage 冻结为本地 Source
         ↓
-Diagnose / Grill / ELI5 / Wayfinder / Prototype / Code Review / Architecture Review
+Diagnose / Grill / Wayfinder / Prototype / Code Review / Architecture Review
         ↓
 Spec             外部行为、范围、验收合同与关键约束
         ↓
@@ -52,7 +52,6 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
 
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
@@ -101,7 +100,6 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/prototypes/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>`
 
 ## 全局治理原则
 
@@ -190,7 +188,6 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 | 本地 change 完成且来源可关闭 | T-triage reconcile | A |
 | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
 | 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
-| 需要向刚上大一、没有专业背景的读者做 Markdown 与 ASCII 图解 | E-eli5 | 返回用户 / 继续当前 change |
 | 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
 | 需要用代码回答逻辑/UI 问题 | P-prototype | G / S / T / I |
 | 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
@@ -209,8 +206,6 @@ Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/sp
 - **A-archive-and-consolidate** — 归档与沉淀：校验本地完成与远程 reconcile 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
 - **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
 - **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
-- **E-eli5** — 零基础新生解释：面向刚上大一、没有专业背景的读者解释一个主题；用 Markdown 和 ASCII 图解说明概念、数据与调用如何流动。
-- **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
 - **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
 - **I-implement** — 实现：基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
 - **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -20,7 +20,6 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
 | 原型记录 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
-| 零基础新生图解 | `<Path>{roots.state}/specdev/changes/{change}/eli_index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/<number>_<topic>.md</Path>` | 面向刚上大一、没有专业背景读者的 Markdown 与 ASCII 图解；索引按序号持续追加 | 产品决定、架构决定或实现授权 |
 | Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |