@namewta/speculo 0.8.4 → 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/A-archive-and-consolidate/A-archive-and-consolidate.md

@@ -9,6 +9,8 @@ keywords: [归档, consolidation, ADR, context, research, knowledge, 代码库
 
 # 归档与沉淀
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 A 是 SpecDev 的归档 wrapper：它拥有模式选择、SpecDev 完成门和代码访谈；机械扫描、dry-run、知识毕业、合并、清理、移动与重读由 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 单一维护。
 
 ## 模式

package/template/workflows/specdev/C-code-review/C-code-review.md

@@ -9,6 +9,8 @@ keywords: [code-review, review, diff, fixed-point, PR, 标准, 规范]
 
 # 代码审查
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 C 是独立 review 入口，不实施修复。它拥有 `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`；I 的最终审查由 I 写入 Evidence，不写本目录。
 
 ## 输入

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -9,6 +9,8 @@ keywords: [bug, 诊断, 红灯, tight-loop, 根因, 复现, 假设]
 
 # 诊断 Bug
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 D 的主导词是**红灯**：没有一条已执行且能在此 bug 上变红的紧凑命令，就没有可进入的假设阶段。D 默认只读项目代码，可以创建 change 诊断工件和经授权的临时可撤销探针；生产修复由 Implement 拥有。
 
 ## 输入与所有权

package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md

@@ -9,6 +9,8 @@ keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决
 
 # 设计访谈（带文档）
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 不留情面地访谈用户，直到达成共识。把这件事映射为一棵**设计树（design tree）**：每个决策都会分出挂在它下面的后续决策。
 
 按**轮次**推进这棵树。**前沿（frontier）** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier；用户的答案会重塑设计树并解除下一层问题的阻塞。

package/template/workflows/specdev/I-implement/I-implement.md

@@ -9,6 +9,8 @@ keywords: [实现, TDD, Lead, subagent, worktree, current workspace, direct-pare
 
 # 实现
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 本 work 保留模块设计检查、design-it-twice、TDD 红绿循环、双轴审查和证据治理。Ticket 模式按 Goal Plan 的 `ticket_workspace_policy` 选择 current workspace 串行直接父分支或独立 worktree candidate-merge；Lead 根据实际情况自行实现或动态派单。
 
 ## 执行模式

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -9,11 +9,13 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 # 初始化设置
 
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+
 首次使用 SpecDev、状态根不存在或治理契约发生变化后运行。此 work 只初始化 SpecDev 的状态与配置，不修改项目业务代码。
 
 ## 规范输入
 
-- 工作流总览：`<Path>{roots.workflows}/specdev/INDEX.md</Path>`
+- 工作流运行合同：`<Path>{roots.workflows}/specdev/README.md</Path>`
 - 路径引用契约：`<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
 - 配置模板：`<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
 - 配置 Schema：`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`