@namewta/speculo 0.8.13 → 1.0.2

package/template/workflows/learning/_state/status.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "workflow": "learning",
   "active": [],
   "archived": []

package/template/workflows/learning/common/rules/activation-and-memory.md

@@ -0,0 +1,20 @@
+# Activation and memory retrieval protocol
+
+本规则只在用户明确激活当前 workflow 或某个 Work 后读取。INDEX 只用于被动发现，不初始化状态、不读取 active change、不写入知识。
+
+## Locate before read
+
+1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
+2. 根据当前请求、Work 分支、关键词、状态和 provenance 定位最小相关 entry。
+3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
+4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。
+
+## Memory writes
+
+正式知识、永久 context、synthesis 或 archive 写入前，先解析唯一 owner 与 gateway，检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时，只阻塞记忆写入，继续独立的只读审计、定位和验证。
+
+每次写入必须记录 source IDs、证据定位、验证时间或 digest；写入后重新读取索引和目标 entry，确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
+
+## Read budget
+
+当前 Work 的权威状态、schema、Map/Plan、当前输入和直接所有权合同可以完整读取；非当前分支的知识树、历史 change、研究库、项目 Skill 和示例只按索引与关键词读取。执行、冲突、恢复和归档 Work 需要完整证据时，以该 Work 的显式合同为准。

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

@@ -1,27 +1,13 @@
-# Learning 工件合同
+# Learning v2 工件合同
 
-## 权威与所有权
-
-| 工件 | Owner | 权威内容 |
+| 工件 | Owner | 规则 |
 | --- | --- | --- |
-| `intake.md` | A-assess | 学习对象、动机、范围和约束 |
-| `baseline.md` | A-assess | 未教学前的已有能力证据 |
-| `learning-plan.md` | A-assess | 目标、关键目标、前置知识、完成证据和深度 |
-| `sources.md` | A-assess / E-eli5 | 来源、定位、可信度和已验证范围 |
-| `lessons/` | E-eli5 | 教学解释、图解、类比及边界 |
-| `practice/` | P-practice | 原始练习作答、提示层级和反馈 |
-| `quiz/*-response.md` | 学习者 | 不经改写的原始答案 |
-| `quiz/*-result.md` | Q-quiz / R-review | 按锁定 rubric 产生的评分和差距 |
-| `promotion-plan.md` | A-archive | 待创建、合并、取代、索引更新和归档动作 |
-| `context/` | A-archive；R 仅限复习状态 | 当前已掌握知识 |
-| `archive/` | A-archive | 不可变学习历史 |
-
-冲突时按实际事实、学习者原始作答、锁定目标/rubric、测验 result、promotion plan、永久知识、课程解释和索引摘要的顺序裁决。状态 JSON 只是投影，必须与上述工件一致。
-
-## 不变量
-
-- `baseline.md` 必须在首份 lesson 前形成；缺失时不能宣称教学适配了背景。
-- 目标内容可以澄清但不能在看到测验结果后静默降低；实质变化创建修订记录并重新测验。
-- AI 不得改写学习者答案后再评分。
-- 未同时通过即时和保持门的内容只能留在 change，不能进入 context。
-- 归档内容只读；纠正通过新 change 和 supersedes 关系完成。
+| `course.md`、`background/`、`baseline.md`、`sources.md`、Change `INDEX.md` | A-assess-and-plan | 目标、宏观基础、原始基线、来源和课程地图；实质修改留 revision |
+| `lessons/` | L-lesson | 完整 Lesson 和 Lesson INDEX；不写作业答案或掌握结论 |
+| `homework/` | H-homework + learner | H 写问题/评审，learner 写 A；提交后只追加 Review，旧 attempt 不可改写 |
+| `review/` | R-review | 延迟保持题、原始回答、证据和复习日期 |
+| `children/<id>/` | child Work | 子 Change 原有工件；父只负责根锁、路由、位置登记 |
+| `synthesis/`、topic context | C-consolidate | claim 级综合、冲突、空白、provenance 和版本；不得覆盖原料 |
+| `archive/`、locations projection | A-archive | 用户关闭后的物理移动和只读登记；不判断掌握、不写 context |
+
+状态 JSON 只是 projection；真实内容、学习者原始回答、评审和 source manifest 是证据权威。

package/template/workflows/learning/common/rules/assessment-policy.md

@@ -1,7 +1,12 @@
-# 评估与评分政策
+# 作业与评审政策
 
-学习计划在教学前锁定 objective id、关键性和验收证据。最终题目不得简单复述课程示例；评分 rubric 必须在作答前固定，但答案或评分结论只在学习者提交原始 response 后读取或形成。
+H 将教学和评估分开。生成作业时只提供问题和必要的作答边界，不泄露答案；用户必须在同一文件加入 `Submission: ready` 才会进入评审。
 
-每次测验覆盖主动回忆、因果/结构解释、新情境迁移和常见误区辨析。题目、原始 response、result 分文件保存；重试使用新变式和递增 attempt 编号，不覆盖旧证据。
+默认五题分别覆盖回忆/定义、机制/为什么、变式应用、全新情境迁移和误区辨析。每题评审必须写：
 
-Result 对每个 objective 列出：得分、引用的 response、正确处、差距、证据来源和置信度。主观或来源冲突项使用 `needs_review`。失败 result 必须形成最小补救范围，路由回 E 或 P，不扩大整个课程。
+- `verdict`: `correct | partial | incorrect | uncertain`；
+- 回答覆盖了什么、缺了什么和引用的 Lesson/source anchor；
+- 中文详细讲解和 `Explain (English)`；
+- 误区、修正路径和下一步。
+
+H 不要求固定百分比，也不把 immediate 评审自动称为 mastered。题目/回答/评审在单文件内按段落追加；重答创建新 attempt。评分无法裁决时使用 `uncertain` 并保留 blocker。

package/template/workflows/learning/common/rules/knowledge-organization.md

@@ -1,9 +1,7 @@
-# 图书式知识组织
+# 主题知识组织与溯源
 
-Learning 只使用 Markdown 目录和精确链接：`context/INDEX.md` 指向领域 `INDEX.md`，领域索引指向具体知识文件。允许 `rg` 修复索引，但不建设向量、Embedding、chunk、相似度或 rerank 层。
+被动入口是 `context/INDEX.md` -> `domains/<domain>/topics/<topic-id>/INDEX.md` -> 精确主题文件。主题视图是 C 生成的派生物，不是原始课程或作业的替代品。
 
-领域目录使用稳定 kebab id；领域类型为 project、product、subject、language 或 skill。每个领域包含 `INDEX.md`、`overview.md`，并按真实需要创建 `concepts/`、`methods/`、`adr/`，不为空架构预建无用途目录。
+每个 claim 记录稳定 `claim_id`、陈述、`evidence_status`（`draft|supported|contested|unresolved`）、source Change ID、Lesson/Homework/Review anchor、外部 source ID、验证时间和冲突/空白。所有链接用 `{roots.*}` aliases；物理 relocation 后由 `locations.json` 按 Change ID 解析当前路径。
 
-知识文件必须包含元数据表：Knowledge ID、状态、前置知识、相关知识、掌握证据、最近验证、下次复习；正文包含当前理解、心智模型、示例与应用、常见误区、来源与证据。状态只允许 `mastered | review_due | needs_refresh | superseded`。
-
-同主题存在时合并当前真相；新事实推翻旧结论时改写当前文件并记录 `supersedes` 归档证据；仅相关时互链，不复制正文。更新顺序为知识叶子、领域 INDEX、context/INDEX、REVIEW。索引只保存导航摘要，不保存课程全文或会话历史。
+只有 R 的真实 retention evidence 才能把 claim/status 标为 `retention_verified` 或 `mastered`。C 可以综合未掌握材料，但必须保留 evidence status，不能从综合文本推断掌握。

package/template/workflows/learning/common/rules/mastery-policy.md

@@ -1,21 +1,5 @@
-# 掌握与复习政策
+# 掌握与复习政策 v2
 
-## 双重掌握门
+即时理解来自 H 的逐题评审，字段为 `mastery.immediate` 和 objective/transfer projection；H 评审后可以结束当前轮次。没有固定 80% 门槛，也不要求 Homework、R 或掌握才能使用 A-archive。
 
-即时门验证当前理解；保持门验证间隔后的回忆和迁移。即时通过只把 change 设置为 `awaiting_retention`，默认首次保持测验安排在至少 24 小时后。学习者可以在 profile 中选择更长间隔，但不得把零间隔称为保持证据。
-
-两个门都必须满足：总分至少 80%；所有关键目标通过；至少一道新情境迁移题通过；没有阻塞性误解。无法客观裁决的答案标记 `needs_review`，在用户或独立证据确认前不得通过。
-
-## 周期复习
-
-默认复习间隔为通过保持门后的 7、30、90 天。R 根据真实日期和上次证据安排；不伪造未来完成。周期复习失败不删除 archive，而是创建 remediation change，并把当前知识标记为 `needs_refresh`。
-
-## 证据强度
-
-- 项目：准确定位、调用或数据流预测、可重复命令/测试、小型安全任务。
-- 产品：用户、问题、约束、指标、取舍和新场景判断。
-- 学科：回忆、因果解释、计算/推导或反例、迁移应用。
-- 语言：理解、主动产出、纠错、不同语境迁移。
-- 技能：独立执行、可观察结果、错误诊断和变式任务。
-
-不引入 BKT、FSRS 或概率熟练度模型。只有积累了足以验证收益的历史数据后，才通过新 change 决定是否增加算法。
+保持掌握只能来自 R：必须在真实间隔后重新回忆、解释、反例和新情境迁移；时间未到只能记录 due date。通过后设置 `mastery.retention=passed`、`mastery.overall=retention_verified`，并允许 context 标记 mastered。失败不删除历史，必要时建立补救 Lesson/Change。

package/template/workflows/learning/common/rules/path-reference-contract.md

@@ -1,7 +1,5 @@
-# Learning 路径引用合同
+# Learning v2 路径与引用
 
-静态 Learning 文件使用完整 `<Path>{roots.workflows}/learning/<relative-path></Path>`；运行时状态使用完整 `<Path>{roots.state}/learning/<relative-path></Path>`。不得使用机器绝对路径、反斜杠、`..`、裸文件名或把 workflow `_state` 当作运行时目录。
+稳定标识是 `change_id`、`lesson_id`、`homework_id`、`review_id` 和 `topic_id`；`locator` 只是当前位置：`changes/<id>`、`changes/<parent>/children/<id>` 或 `archive/YYYY-MM/<root>`。跨工件引用同时写 stable ID 和 `<Path>{roots.state}/learning/</Path>` 下的当前 locator。
 
-`{change}` 是启动协议选择的 change 名；`{domain}` 来自 `learning-plan.md` 和 change 状态；`YYYY-MM` 从 change 日期前缀派生。项目证据使用项目根相对路径，外部来源使用真实 URL。
-
-动态知识路径必须先由 promotion plan 明确，确认后才允许创建或改写。完整路径只确定对象，不授予副作用权限。
+`locations.json` 保存历史 locator、relocation 时间/原因和源目录哈希。新工件不得把旧路径当作永久链接；validator 必须跟随位置登记解析。源 Markdown 的相对链接在移动后由 owner 修正为 alias/ID 引用，已经提交的 Homework、Review 和 archive 内容不改写。

package/template/workflows/learning/common/rules/teaching-policy.md

@@ -1,15 +1,15 @@
-# 通俗教学政策
+# 完整课程教学政策
 
-每次教学必须明确写出一个直接、具体的教学表达基线，例如“5 岁的小孩”或“大一新生”。不要把它改写成“普通初学者”“低门槛读者”或“没有专业背景的人”；这些抽象说法不能给出足够稳定的表达约束。用户没有指定时，默认使用“5 岁的小孩”。
+## 深度与表达
 
-教学表达基线直接约束讲法：
+`expression_level=eli5|plain` 只控制词汇、句法、脚手架和类比；`coverage_depth=overview|standard|deep` 控制事实、机制、边界、例子和迁移的覆盖。ELI5 不是删减内容，类比必须紧跟失效边界和精确定义。
 
-- **5 岁的小孩**：使用短句、具体物体和日常动作；一次只引入一个新概念；先说现象和用途，再给名称；不预设公式、专业术语或行业经验。
-- **大一新生**：可以使用基础逻辑、简单公式和抽象分类，但不预设专业课程、项目经验或行业惯例；每个首次出现的术语仍需定义。
-- **其他基线**：必须由用户明确指定，并写清可以预设的语言、数学、学科或实践基础。
+## 时间与结构
 
-教学表达基线只决定如何讲，不代表学习者在该领域已经掌握什么。内容深度由 baseline 和经过索引、知识正文确认的 context 证据决定；已掌握概念可以作为桥梁，未验证内容不得当作基础。
+标准 Lesson 的 `estimated_minutes` 为 30–40（默认 35），由 orientation、解释、视觉/示例、暂停和总结等 `time_budget` 加总；不以字符数作为时长证据。章节次序可按主题变更，但每个 OBJ 至少有动机/宏观地图、直觉、术语/English term、机制、文本视觉和文字等价物、正例、反例/边界、变式迁移、误区、总结和来源。
 
-所有图解只使用 fenced code block 中的纯文本 ASCII，不使用 Mermaid、HTML、SVG 或其他依赖渲染器的格式。每张图只回答一个问题，箭头有方向；文字解释关系，不逐字重复图。首次出现术语时先给日常说法，再给专业名称。类比必须标出“哪里相像、哪里不相像”。
+## 图文与来源
 
-教学采用脚手架递减：示范一个、共同完成一个、学习者独立完成一个。学习者未尝试前先给逐级提示，不直接泄露完整答案。解释结束不等于学会，必须进入练习和测验。
+ASCII、Markdown table、公式或可选外链图片可以组合使用；每个视觉必须有 caption、alt 和附近的完整文字等价物，外链失效不能阻塞理解。`sources.md` 和 Lesson source table 记录 URL、标题、定位、访问日期、claim 映射、可信度和不确定性；无法验证的内容明确标为 open/uncertain。
+
+Lesson 可以有非评分 pause/self-check，但不含 Q/A、答案、分数、verdict 或 mastered 字段。

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

@@ -1,41 +1,69 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:learning:change-status:v1",
-  "title": "Learning Change Status",
+  "$id": "urn:speculo:learning:change-status:v2",
+  "title": "Learning Change Status v2",
   "type": "object",
-  "required": ["schema_version", "artifact", "change", "domain", "domain_type", "topic", "change_status", "phase", "current_work", "works_run", "created_at", "updated_at", "completed_at", "archived_at", "archive_path", "mastery", "blockers"],
+  "required": ["schema_version", "artifact", "change_id", "kind", "domain", "domain_type", "topic_id", "parent_change", "root_change", "locator", "lifecycle", "phase", "current_work", "works_run", "created_at", "updated_at", "closed_at", "archived_at", "closure_reason", "archive_path", "homework", "mastery", "children", "blockers"],
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"const": 2},
     "artifact": {"const": "learning-change-status"},
-    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change_id": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "kind": {"enum": ["learning", "consolidation"]},
     "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
     "domain_type": {"enum": ["project", "product", "subject", "language", "skill"]},
-    "topic": {"type": "string", "minLength": 1},
-    "change_status": {"enum": ["active", "blocked", "awaiting_retention", "completed", "archived"]},
-    "phase": {"enum": ["intake", "assessment", "teaching", "practice", "immediate_quiz", "retention", "ready_to_archive", "archived"]},
+    "topic_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "parent_change": {"type": ["string", "null"]},
+    "root_change": {"type": "string"},
+    "locator": {"type": "string", "pattern": "^(?:changes/.+|archive/[0-9]{4}-[0-9]{2}/.+)$"},
+    "lifecycle": {"enum": ["active", "blocked", "closed", "archived"]},
+    "phase": {"enum": ["planning", "teaching", "homework", "review", "consolidating", "closed", "archived"]},
     "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
     "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true},
     "created_at": {"type": "string", "format": "date-time"},
     "updated_at": {"type": "string", "format": "date-time"},
-    "completed_at": {"type": ["string", "null"], "format": "date-time"},
+    "closed_at": {"type": ["string", "null"], "format": "date-time"},
     "archived_at": {"type": ["string", "null"], "format": "date-time"},
-    "archive_path": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/learning/archive/[0-9]{4}-[0-9]{2}/[^<]+</Path>$"}]},
+    "closure_reason": {"type": ["string", "null"]},
+    "archive_path": {"type": ["string", "null"]},
+    "homework": {
+      "type": "object",
+      "required": ["status", "latest_id", "submitted_at"],
+      "properties": {
+        "status": {"enum": ["none", "pending", "reviewed", "needs_revision"]},
+        "latest_id": {"type": ["string", "null"]},
+        "submitted_at": {"type": ["string", "null"], "format": "date-time"}
+      },
+      "additionalProperties": false
+    },
     "mastery": {
       "type": "object",
-      "required": ["immediate", "retention", "score", "critical_objectives_passed", "transfer_passed", "blocking_misconceptions", "evidence", "next_review_at"],
+      "required": ["overall", "immediate", "retention", "critical_objectives", "transfer", "blocking_misconceptions", "evidence", "next_review_at"],
       "properties": {
-        "immediate": {"enum": ["not_attempted", "failed", "passed", "needs_review"]},
-        "retention": {"enum": ["not_attempted", "failed", "passed", "needs_review"]},
-        "score": {"type": ["number", "null"], "minimum": 0, "maximum": 100},
-        "critical_objectives_passed": {"type": "boolean"},
-        "transfer_passed": {"type": "boolean"},
+        "overall": {"enum": ["unverified", "immediate", "retention_verified"]},
+        "immediate": {"enum": ["not_attempted", "passed", "needs_review"]},
+        "retention": {"enum": ["not_scheduled", "due", "passed", "needs_review"]},
+        "critical_objectives": {"enum": ["not_attempted", "passed", "needs_review"]},
+        "transfer": {"enum": ["not_attempted", "passed", "needs_review"]},
         "blocking_misconceptions": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-        "evidence": {"type": "array", "items": {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/learning/(?:changes/[^<]+|archive/[0-9]{4}-[0-9]{2}/[^<]+)/quiz/[^<]+\\.md</Path>$"}, "uniqueItems": true},
+        "evidence": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
         "next_review_at": {"type": ["string", "null"], "format": "date-time"}
       },
       "additionalProperties": false
     },
-    "blockers": {"type": "array", "items": {"type": "string"}, "uniqueItems": true}
+    "children": {"type": "array", "items": {"$ref": "#/$defs/child"}, "uniqueItems": true},
+    "blockers": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "child": {
+      "type": "object",
+      "required": ["change_id", "locator", "content_hash", "effective_at", "lifecycle"],
+      "properties": {
+        "change_id": {"type": "string"},
+        "locator": {"type": "string"},
+        "content_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "effective_at": {"type": "string", "format": "date-time"},
+        "lifecycle": {"type": "string"}
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

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

@@ -1,32 +1,33 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:learning:status:v1",
-  "title": "Learning Global Status",
+  "$id": "urn:speculo:learning:status:v2",
+  "title": "Learning Global Status v2",
   "type": "object",
   "required": ["schema_version", "workflow", "active", "archived"],
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"const": 2},
     "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
-    }
+    "active": {"type": "array", "items": {"$ref": "#/$defs/entry"}},
+    "archived": {"type": "array", "items": {"$ref": "#/$defs/entry"}}
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "required": ["change_id", "kind", "domain", "topic_id", "locator", "parent_change", "root_change", "current_work", "works_run"],
+      "properties": {
+        "change_id": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "kind": {"enum": ["learning", "consolidation"]},
+        "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "topic_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "locator": {"type": "string", "pattern": "^(?:changes/.+|archive/[0-9]{4}-[0-9]{2}/.+)$"},
+        "parent_change": {"type": ["string", "null"]},
+        "root_change": {"type": "string"},
+        "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
+        "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true},
+        "updated_at": {"type": "string", "format": "date-time"}
+      },
+      "additionalProperties": false
+    }
+  }
 }

package/template/workflows/learning/common/skills/topic-synthesis/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: topic-synthesis
+description: 将 Learning Change 作为不可变原料，生成带 claim 级 provenance 的主题综合并显式发布。
+---
+
+# Topic Synthesis
+
+1. 只接收 C-consolidate 已确认的 source manifest；按稳定 Change ID 读取当前 locator，禁止依赖旧路径猜测。
+2. 对每个 claim 记录 source Change、Lesson/Homework/Review anchor、外部 source id、证据状态、冲突、空白和验证时间；不要把类比或索引摘要当成事实来源。
+3. 生成新的 `synthesis/revisions/<version>.md`，旧版本只读保留。综合可以包含未掌握证据，但不得写 `mastered`，除非 R evidence 已存在。
+4. 发布 context 前必须再次获得用户确认；发布只更新 topic INDEX/current view 和 provenance，不删除或改写任何 child 原料。
+
+## 引用模板
+
+| claim_id | 陈述 | evidence_status | source_change_id | artifact anchor | external source | verified_at |
+| --- | --- | --- | --- | --- | --- | --- |
+| CLM-001 | `<claim>` | supported | `<change-id>` | `L-001#heading` | `S-001` | `<ISO-8601>` |

package/template/workflows/learning/common/skills/topic-synthesis/claim-template.md

@@ -0,0 +1,15 @@
+# Claim <CLM-NNN>
+
+## 陈述
+
+## Evidence status
+
+`draft | supported | contested | unresolved`
+
+## 来源与定位
+
+- Change ID / current locator：
+- Lesson/Homework/Review anchor：
+- External source ID / URL / access date：
+
+## 冲突、空白与下一次验证

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

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const CHANGE_ID = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function args(argv) {
+  const result = { stateRoot: null, parent: null, sources: [], apply: false, rollback: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--state-root") result.stateRoot = resolve(argv[++index] ?? "");
+    else if (arg === "--parent") result.parent = argv[++index] ?? null;
+    else if (arg === "--source") result.sources.push(argv[++index] ?? "");
+    else if (arg === "--apply") result.apply = true;
+    else if (arg === "--rollback") result.rollback = resolve(argv[++index] ?? "");
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  if (!result.stateRoot) throw new Error("--state-root is required");
+  if (result.rollback) return result;
+  if (!result.parent || !CHANGE_ID.test(result.parent) || result.sources.length === 0) {
+    throw new Error("--parent and at least one --source are required");
+  }
+  if (result.sources.some((source) => !CHANGE_ID.test(source)) || new Set(result.sources).size !== result.sources.length) {
+    throw new Error("source ids must be unique valid Change IDs");
+  }
+  if (result.sources.includes(result.parent)) throw new Error("a parent cannot be one of its own sources");
+  return result;
+}
+
+async function json(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function files(root) {
+  const result = [];
+  async function visit(current) {
+    const entries = await (await import("node:fs/promises")).readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile()) result.push(path);
+    }
+  }
+  await visit(root);
+  return result.sort();
+}
+
+async function contentHash(root) {
+  const hash = createHash("sha256");
+  for (const path of await files(root)) {
+    const rel = relative(root, path).split(sep).join("/");
+    if (rel === ".status.json") continue;
+    hash.update(rel);
+    hash.update(await readFile(path));
+  }
+  return hash.digest("hex");
+}
+
+async function loadLocations(stateRoot) {
+  const path = join(stateRoot, "locations.json");
+  const value = await json(path, { schema_version: 2, workflow: "learning", entries: [] });
+  if (value.schema_version !== 2 || value.workflow !== "learning" || !Array.isArray(value.entries)) {
+    throw new Error("locations.json must use Learning schema v2");
+  }
+  return { path, value };
+}
+
+function locatorFor(entry, stateRoot) {
+  const locator = entry?.locator;
+  if (typeof locator === "string" && (locator.startsWith("changes/") || locator.startsWith("archive/"))) return locator;
+  return `changes/${entry.change_id}`;
+}
+
+function updateLocation(value, id, from, to, hash, now, parent) {
+  const existing = value.entries.find((entry) => entry.change_id === id);
+  if (existing) {
+    existing.previous = Array.isArray(existing.previous) ? existing.previous : [];
+    existing.previous.push({ locator: from, moved_at: now, reason: "consolidate", content_hash: hash });
+    existing.locator = to;
+    existing.parent_change = parent;
+    existing.root_change = value.entries.find((entry) => entry.change_id === parent)?.root_change ?? parent;
+    existing.content_hash = hash;
+    existing.updated_at = now;
+    return;
+  }
+  value.entries.push({
+    change_id: id,
+    locator: to,
+    parent_change: parent,
+    root_change: parent,
+    content_hash: hash,
+    previous: [{ locator: from, moved_at: now, reason: "consolidate", content_hash: hash }],
+    updated_at: now,
+  });
+}
+
+async function updateStatus(path, id, to, parent, now) {
+  const statusPath = join(path, ".status.json");
+  if (!existsSync(statusPath)) return;
+  const value = await json(statusPath, null);
+  if (!value || value.schema_version !== 2 || value.change_id !== id) return;
+  value.parent_change = parent;
+  value.root_change = value.root_change === id ? parent : value.root_change;
+  value.locator = to;
+  value.updated_at = now;
+  await writeFile(statusPath, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+async function updateGlobalStatus(stateRoot, ids, parent, now) {
+  const path = join(stateRoot, "status.json");
+  const value = await json(path, null);
+  if (!value || value.schema_version !== 2) return;
+  const root = value.active.find((entry) => entry.change_id === parent)?.root_change ?? parent;
+  for (const entry of [...value.active, ...value.archived]) {
+    if (!ids.includes(entry.change_id)) continue;
+    entry.parent_change = parent;
+    entry.root_change = root;
+    entry.locator = entry.locator;
+    entry.updated_at = now;
+  }
+  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+async function rollbackManifest(manifestPath) {
+  const manifest = await json(manifestPath, null);
+  if (!manifest || !Array.isArray(manifest.moves)) throw new Error("invalid relocation manifest");
+  for (const move of [...manifest.moves].reverse()) {
+    if (existsSync(move.to) && !existsSync(move.from)) await rename(move.to, move.from);
+  }
+  await writeFile(manifestPath, JSON.stringify({ ...manifest, rolled_back_at: new Date().toISOString() }, null, 2) + "\n", "utf8");
+  console.log(JSON.stringify({ status: "rolled-back", manifest: manifestPath }));
+}
+
+async function main() {
+  const options = args(process.argv.slice(2));
+  if (options.rollback) {
+    await rollbackManifest(options.rollback);
+    return;
+  }
+  const changesRoot = join(options.stateRoot, "changes");
+  const parentPath = join(changesRoot, options.parent);
+  if (!existsSync(parentPath)) throw new Error(`parent Change does not exist: ${options.parent}`);
+  const { path: locationsPath, value: locations } = await loadLocations(options.stateRoot);
+  const moves = [];
+  for (const id of options.sources) {
+    const entry = locations.entries.find((candidate) => candidate.change_id === id);
+    const fromLocator = locatorFor(entry, options.stateRoot);
+    if (!fromLocator.startsWith("changes/")) throw new Error(`source is not an active/closed Change: ${id}`);
+    const from = join(options.stateRoot, ...fromLocator.split("/"));
+    if (!existsSync(from)) throw new Error(`source Change is missing: ${fromLocator}`);
+    const relativeFrom = fromLocator.split("/");
+    if (relativeFrom.slice(0, 2).join("/") === `changes/${options.parent}` || from === parentPath || parentPath.startsWith(from + sep)) {
+      throw new Error(`source/parent cycle detected for ${id}`);
+    }
+    const to = join(parentPath, "children", id);
+    if (existsSync(to)) throw new Error(`target child already exists: ${id}`);
+    moves.push({ id, from, to, from_locator: fromLocator, to_locator: `changes/${options.parent}/children/${id}` });
+  }
+  const hashes = [];
+  for (const move of moves) hashes.push({ id: move.id, content_hash: await contentHash(move.from) });
+  const now = new Date().toISOString();
+  const manifest = {
+    schema_version: 1,
+    artifact: "learning-relocation-manifest",
+    parent_change: options.parent,
+    created_at: now,
+    moves: moves.map((move) => ({ ...move, content_hash: hashes.find((item) => item.id === move.id).content_hash })),
+  };
+  if (!options.apply) {
+    console.log(JSON.stringify({ status: "dry-run", ...manifest }, null, 2));
+    return;
+  }
+
+  await mkdir(join(parentPath, "children"), { recursive: true });
+  const lockPath = join(options.stateRoot, ".consolidate.lock");
+  let lock;
+  try {
+    lock = await open(lockPath, "wx");
+    for (const move of moves) await rename(move.from, move.to);
+    for (const move of manifest.moves) {
+      updateLocation(locations, move.id, move.from_locator, move.to_locator, move.content_hash, now, options.parent);
+      await updateStatus(join(options.stateRoot, ...move.to_locator.split("/")), move.id, move.to_locator, options.parent, now);
+    }
+    await writeFile(locationsPath, JSON.stringify(locations, null, 2) + "\n", "utf8");
+    await updateGlobalStatus(options.stateRoot, options.sources, options.parent, now);
+    const manifestPath = join(parentPath, "synthesis", `relocation-${now.replaceAll(/[^0-9]/g, "").slice(0, 14)}.json`);
+    await mkdir(dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    console.log(JSON.stringify({ status: "applied", manifest: manifestPath, moves: manifest.moves }, null, 2));
+  } catch (error) {
+    for (const move of [...moves].reverse()) {
+      if (existsSync(move.to) && !existsSync(move.from)) await rename(move.to, move.from);
+    }
+    throw error;
+  } finally {
+    if (lock) await lock.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(`Learning relocation failed: ${error.message}`);
+  process.exitCode = 1;
+});