@namewta/speculo 0.8.13 → 1.0.1

package/template/workflows/learning/I-init-setup/review-index-template.md

@@ -1,4 +1,4 @@
 # 复习目录
 
-| 到期日期 | Knowledge ID | 状态 | 知识文件 | 最近证据 | 下一动作 |
+| 到期日期 | Topic/Lesson ID | 状态 | Review 文件 | 最近证据 | 下一动作 |
 | --- | --- | --- | --- | --- | --- |

package/template/workflows/learning/INDEX.md

@@ -3,24 +3,22 @@ id: learning
 type: workflow
 workflow: learning
 name: Learning Workflow
-description: 以可验证目标、通俗教学、主动练习和延迟测验，将项目、产品、学科、语言或技能学习沉淀为可检索的个人 Markdown 知识。
-keywords: [learning, 学习, 教学, 测验, 复习, 知识, 项目, 产品, 英语, eli5]
+description: 以完整、通俗、多表示的课程，单文件作业评审、可选延迟复习和带溯源的主题综合，持续建立个人 Markdown 知识库。
+keywords: [learning, 学习, 教学, 作业, 复习, 综合, 知识, eli5]
 ---
 
 # Learning Index
 
-本索引用于发现 Learning，并让未激活状态机的会话按图书目录方式读取已经掌握的知识。Learning 不使用 RAG、向量数据库、Embedding、语义分块或重排器。
+本索引只用于被动发现 Learning 和已发布的主题知识；被动读取不得初始化状态、创建 Change 或修改复习状态。需要执行 Work 时必须读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
 
-## 永久知识
-
-只读取当前请求需要且实际存在的索引或知识文件；路径不存在时静默跳过。被动读取不得初始化状态、创建 change 或修改复习状态：
+## 永久知识（主题视图）
 
 - 总目录：`<Path>{roots.state}/learning/context/INDEX.md</Path>`
+- 主题目录：`<Path>{roots.state}/learning/context/domains/{domain}/topics/{topic-id}/INDEX.md</Path>`
 - 复习目录：`<Path>{roots.state}/learning/context/REVIEW.md</Path>`
-- 领域知识：`<Path>{roots.state}/learning/context/domains/</Path>`
 
-检索顺序固定为总目录、领域 `INDEX.md`、精确知识文件。索引缺失或链接失效时可以用 `rg` 在 Learning state 根内定位候选，但搜索结果不是知识权威，必须回到真实 Markdown 文件核对。
+主题文件是带 evidence status 和 provenance 的派生视图；原始课程、作业和回答始终回到对应 Change 核对。
 
 ## Work 激活
 
-用户明确激活 Learning 或其中某个 Work 后，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，取得 Work 条目、启动、恢复、状态、所有权、掌握门和副作用合同。仅发现本索引或读取永久知识不加载该合同。
+用户明确激活 Learning 或指定 Work 后，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，按 v2 状态、位置登记和 ownership 合同恢复或创建 Change。Work 的建议下一步不构成自动授权。

package/template/workflows/learning/L-lesson/L-lesson.md

@@ -0,0 +1,32 @@
+---
+id: learning/lesson
+type: workflow-entry
+workflow: learning
+name: 完整课程讲解
+description: 一次输出 30–40 分钟、通俗但完整的 Lesson；不生成作业、不评分、不宣称掌握。
+keywords: [lesson, 教学, eli5, 图文, explanation]
+---
+
+# 完整课程讲解
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
+
+## 流程
+
+1. 确认 Change 有 `course.md`、`background/foundation.md`、`baseline.md`、目标 OBJ 和 `sources.md`；缺失时返回 A-assess-and-plan。
+2. 用户指定 Lesson 主题、OBJ、期望效果和深度；读取精确背景和来源，不遍历无关 context。
+3. 生成一个完整的 `lessons/L-<NNN>-<slug>.md`，元数据包含 `lesson_id`、`objective_ids`、`estimated_minutes` 30–40、`time_budget`（各段可加总）、`expression_level`、`coverage_depth` 和 `source_ids`。
+4. 每个核心目标至少覆盖动机/宏观地图、通俗直觉、精确定义与英文术语、机制/因果链、ASCII/表格/可选外链图之一及文字等价物、正例、反例或边界、变式迁移、常见误区、总结和引用。允许章节顺序变化，不套用固定 5E 或单一路线。
+5. 可加入非评分 pause/self-check，但不写 Q/A、答案、verdict、分数或 mastered。更新 `lessons/INDEX.md` 与 `learning-log.md`，运行 validator，清空 current_work。
+
+## 完成标准
+
+- Lesson 的活动预算合计 30–40 分钟，内容覆盖矩阵完整，不能用字符数替代时间估计；
+- ELI5 只降低表达门槛，不删去深度、边界、证据或不确定性；
+- 外链图片有 alt/caption/source/访问日期和完整文字替代，链接失效不影响理解；
+- 教学和作业严格分离，用户可稍后主动激活 H。
+
+## 子文件
+
+- Lesson 模板：`<Path>{roots.workflows}/learning/L-lesson/lesson-template.md</Path>`
+- 教学规则：`<Path>{roots.workflows}/learning/common/rules/teaching-policy.md</Path>`

package/template/workflows/learning/L-lesson/lesson-template.md

@@ -0,0 +1,51 @@
+---
+lesson_id: L-<NNN>
+objective_ids: [OBJ-01]
+estimated_minutes: 35
+time_budget:
+  - segment: orientation-and-map
+    minutes: 4
+  - segment: deep-explanation
+    minutes: 16
+  - segment: visuals-and-worked-examples
+    minutes: 9
+  - segment: recap-and-transfer
+    minutes: 6
+expression_level: eli5
+coverage_depth: standard
+source_ids: [S-001]
+---
+
+# Lesson <NNN>：<主题>
+
+## 学完你能做什么
+
+## 先把全局地图放在桌上
+
+## 核心概念与机制
+
+### 直觉讲解
+
+### 精确定义与 English term
+
+### 机制/因果链
+
+### 图、表或文本图
+
+图后必须有完整的文字等价物和图的边界说明。
+
+### 正例、反例与边界
+
+## 变式与迁移
+
+## 常见误区
+
+## 非评分暂停
+
+## 总结、词汇表与下一步
+
+## 来源与引用
+
+| Source ID | 来源 | 支持的 claim/段落 | 定位 | 访问日期 |
+| --- | --- | --- | --- | --- |
+| S-001 | `<title and URL>` | `<claim>` | `<page/section>` | `<YYYY-MM-DD>` |

package/template/workflows/learning/R-review/R-review.md

@@ -3,33 +3,28 @@ id: learning/review
 type: workflow-entry
 workflow: learning
 name: 延迟保持与周期复习
-description: 在真实时间间隔后验证回忆和迁移，决定新知识能否掌握或已归档知识是否需要刷新。
-keywords: [复习, retention, spaced-review, transfer, review-due]
+description: 用户主动指定后，用真实时间间隔验证回忆、机制和迁移，并更新 retention evidence。
+keywords: [复习, retention, spaced-review, transfer]
 ---
 
 # 延迟保持与周期复习
 
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`，再执行本入口。
-
-R 有两个模式：`retention-gate` 处理 awaiting_retention change；`periodic-review` 从 REVIEW 选择已归档知识并创建新的 review change。时间未到时只报告日期，不伪造完成。
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
 
 ## 流程
 
-1. 确定模式。多个到期项或 active change 时请求消歧；周期复习必须创建新 change，不能改写 archive。
-2. 读取 mastery policy、原 learning plan 或知识文件中的掌握目标与证据。保持测验不得简单复用即时题或刚看过的课程示例。
-3. 创建 `quiz/retention-NN-questions.md`，等待并保存原始 response，再按 assessment policy 写 result；顺序和评分合同与 Q 相同。
-4. 失败或 needs_review：保持 change active，写补救范围并路由 E/P。周期复习失败时调用 knowledge-promotion 的 `mark-review-state`，经用户确认把相应知识标记 `needs_refresh` 并更新 REVIEW；archive 保持不变。
-5. 首次保持门通过：设置 retention=`passed`、phase=`ready_to_archive`、change_status=`completed` 和 `completed_at`；记录即时与保持 result 路径，路由 A-archive。
-6. 周期复习通过：result 成为新证据；调用 `mark-review-state` 更新最近验证和下一复习日期。完成 review change 后仍通过 A-archive 归档本次复习历史。
+1. 用户明确指定 Lesson、Homework、Change 或 topic；读取对应的 sources、目标和过去证据。没有真实间隔时只记录 `due_at`，不伪造通过。
+2. 在 Change 的 `review/INDEX.md` 和 `review/RV-<id>.md` 生成新复习记录。题目必须包含延迟回忆、机制/反例和新的迁移情境，不复制刚看过的示例。
+3. 原样保存回答并给出逐项证据；失败只生成补救范围和 `needs_review`，不删除历史、不改写 archived 原文。
+4. 只有通过真实延迟复习才设置 `mastery.retention=passed`、`mastery.overall=retention_verified`，并在 context topic view 标记 `mastered`。R 完成后不自动激活 A。
 
 ## 完成标准
 
-- 保持证据发生在真实间隔后，并含新的迁移情境；
-- 双门未通过时不会设置 completed；
-- 失败只改变当前知识状态，不删除历史证据；
-- 所有 context 改写有明确确认、精确路径和重读验证。
+- 时间、来源、题目和回答可审计；
+- R 是可选 Work，H 的 immediate 评审可以结束当前学习轮次；
+- 周期复习失败保留原证据并建立新的补救 Change 或 note。
 
-## 子文件引用
+## 子文件
 
-- 复习模板：`<Path>{roots.workflows}/learning/R-review/review-template.md</Path>`
-- 知识更新过程：`<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/SKILL.md</Path>`
+- Review 模板：`<Path>{roots.workflows}/learning/R-review/review-template.md</Path>`
+- Topic 状态规则：`<Path>{roots.workflows}/learning/common/skills/topic-synthesis/SKILL.md</Path>`

package/template/workflows/learning/R-review/review-template.md

@@ -1,12 +1,19 @@
-# Review Plan
+# 延迟复习：<Lesson 或 topic>
 
-| Knowledge ID | 上次验证 | 本次到期 | 模式 | 覆盖目标 | 新迁移情境 |
-| --- | --- | --- | --- | --- | --- |
+| 字段 | 值 |
+| --- | --- |
+| Review ID | RV-<id> |
+| 引用 Change/Lesson | `<stable id>` |
+| 上次证据 | `<timestamp and path>` |
+| 本次发生时间 | `<timestamp>` |
+| 最短间隔是否满足 | `<yes/no>` |
 
-## 时间门结论
+## 新回忆与迁移题
 
-## 测验工件
+## 学习者原始回答
 
-## 复习后状态
+## 评审与证据
+
+## retention 结论
 
 ## 下一复习日期

package/template/workflows/learning/README.md

@@ -1,46 +1,21 @@
-# Learning Activation Contract
+# Learning v2 Activation Contract
 
-本合同只在用户明确激活 Learning Work 后读取。Learning 把一次学习表示为可恢复 change，把教学过程、作答和测验证据保留在 change 中，只把通过掌握门的当前知识提升到图书式 Markdown context。
+本合同只在用户明确激活 Learning 或其中一个 Work 后读取。Learning 将学习拆成课程设计、完整授课、单文件作业、可选保持复习和用户触发的主题整合；Work 之间不自动串联。
 
 ## Work 条目
 
 <!-- AUTO-INDEX-START -->
 
-- **A-archive-and-consolidate** — 归档并合并已掌握知识：校验即时与保持证据，先 dry-run 再经确认移动 completed change，并按领域合并当前 Markdown 知识与索引。
-- **A-assess-and-plan** — 评估背景并制定学习计划：从学习请求和已有 Markdown 知识中建立未教学基线，锁定目标、前置知识、来源和掌握证据。
-- **E-eli5** — 通俗图解教学：根据已验证背景、明确教学表达基线和锁定目标，用 ASCII 图、短句、类比边界与递减脚手架形成可恢复课程。
-- **I-init-setup** — 初始化学习系统：初始化学习者教学偏好、纯 Markdown 知识目录和可验证的 Learning 状态，不写入任何伪造知识。
-- **P-practice** — 主动练习与自我解释：通过主动回忆、变式练习、自我解释和递减提示生成独立能力证据与最小差距清单。
-- **Q-quiz** — 即时掌握测验：在不泄露答案的前提下对锁定目标执行即时回忆、解释、迁移和误区测验，并产生可审计评分。
-- **R-review** — 延迟保持与周期复习：在真实时间间隔后验证回忆和迁移，决定新知识能否掌握或已归档知识是否需要刷新。
+- **A-archive** — 冷归档：用户明确关闭后移动整个 Change 树到日期目录；不做知识综合或掌握判断。
+- **A-assess-and-plan** — 评估背景并设计课程：以目标和证据为起点建立课程、背景、基线、来源和可变 Lesson 地图。
+- **C-consolidate** — 主题整合：将选定 Change 物理嵌入父 Change，生成带 claim 级 provenance 的可迭代主题综合。
+- **H-homework** — 课程作业与评审：以单一 Markdown 文件生成题目、接收显式提交并追加逐题评审；不与 Lesson 混写。
+- **I-init-setup** — 初始化学习系统：初始化 Learning v2 的教学偏好、空索引、位置登记和可验证状态。
+- **L-lesson** — 完整课程讲解：一次输出 30–40 分钟、通俗但完整的 Lesson；不生成作业、不评分、不宣称掌握。
+- **R-review** — 延迟保持与周期复习：用户主动指定后，用真实时间间隔验证回忆、机制和迁移，并更新 retention evidence。
 
 <!-- AUTO-INDEX-END -->
 
-## 目标与工件链
-
-```text
-[初始化] --> [评估与计划] --> [通俗教学] --> [主动练习] --> [即时测验]
-                                                               |
-                         +-------------------------------------+
-                         |                                     |
-                       失败                                  通过
-                         |                                     |
-                         v                                     v
-                 [通俗教学或练习]                       [延迟保持测验]
-                                                               |
-                                      +------------------------+
-                                      |                        |
-                                    失败                     通过
-                                      |                        |
-                                      v                        v
-                              [通俗教学或练习]          [归档与合并]
-                                                               |
-                                                               v
-                                                     [当前知识与索引]
-```
-
-权威优先级为：实际项目或可靠来源事实；锁定的 `learning-plan.md`；学习者原始作答；测验 result；promotion plan；永久知识。教学类比、模型总结和索引摘要都不能覆盖更高权威。
-
 ## 运行时根
 
 - 工作流根：`<Path>{roots.workflows}/learning/</Path>`
@@ -48,72 +23,102 @@
 
 ## 持久化约定
 
-| 名称 | 路径 | 生成者与时机 |
-| --- | --- | --- |
-| 全局状态 | `<Path>{roots.state}/learning/status.json</Path>` | 安装 seed 创建；各 Work 原子更新索引字段 |
-| 学习者偏好 | `<Path>{roots.state}/learning/learner-profile.md</Path>` | I 首次创建；保存“5 岁的小孩”“大一新生”等明确教学表达基线、交互偏好和复习政策；领域能力另以证据记录 |
-| 活跃 change | `<Path>{roots.state}/learning/changes/{change}/</Path>` | A 或直接激活 Work 时创建 |
-| 历史归档 | `<Path>{roots.state}/learning/archive/YYYY-MM/{change}/</Path>` | A-archive 在双重掌握门和用户确认后移动；归档完成后只读 |
-| 当前知识总目录 | `<Path>{roots.state}/learning/context/INDEX.md</Path>` | I 首次创建；A-archive 自叶到根更新 |
-| 复习目录 | `<Path>{roots.state}/learning/context/REVIEW.md</Path>` | I 首次创建；A-archive 与 R 更新到期状态 |
-| 领域知识 | `<Path>{roots.state}/learning/context/domains/{domain}/</Path>` | A-archive 在确认的 promotion plan 内创建、合并或取代 |
+所有课程、背景、作业、回答、Review、synthesis 和位置登记均写入 `<Path>{roots.state}/learning/</Path>`；工作流模板只提供合同和空骨架。
+
+## Work 图与激活
+
+```text
+I-init-setup -> A-assess-and-plan -> (user chooses) L-lesson
+                                           |\
+                                           | H-homework -> (optional) R-review
+                                           |\
+                                           +-> user questions -> notes/ or a new lesson/change
+
+Any active or closed changes --(user chooses C)--> consolidation parent
+Any closed root tree       --(user chooses A)--> archive/YYYY-MM/<change>
+```
 
-Change 按需包含 `.status.json`、`intake.md`、`baseline.md`、`learning-plan.md`、`sources.md`、`lessons/`、`practice/`、`quiz/`、`learning-log.md`、`promotion-plan.md`、`promotion-staging/` 和 `promotion-rollback/`。后两者只保存本次已确认事务的候选 Markdown、原内容快照和 rollback manifest，成功后随 change 进入 archive。知识正文、索引、课程、练习和测验全部使用 Markdown；JSON 只用于机器状态和 schema 校验，不参与知识检索。
+`L` 完成后只报告已生成的 Lesson 和可选的下一步，不自动激活 `H`；`H` 评审后可结束本轮，不自动激活 `R`、`C` 或 `A`。`C` 和 `A` 都需要用户明确确认，未确认的 dry-run 不得移动或写入 context。
 
 ## 启动协议
 
-1. 解析 roots；读取全局状态。`learner-profile.md` 或 context 索引不存在时先运行 I。
-2. 用户指定 change 优先；唯一 active 直接恢复；多个 active 请求消歧；没有时创建 `YYYY-MM-DD-<kebab-topic>[-NN]`。
-3. 新 change 同时写全局 active entry 和 change `.status.json`；只允许日期前缀且不覆盖同名目录。
-4. Work 开始时在两级状态设置相同 `current_work`。已有其他 Work 时先恢复、取消或显式交接。
-5. 只加载当前 Work、所需 common 和通过索引精确选择的知识文件，不遍历全部 context。
-6. Work 成功后去重更新 `works_run` 并清空 `current_work`；阻塞时保留当前 Work 和 blocker；取消不加入 `works_run`。
-7. 只有 Q 可以记录即时通过，R 可以记录保持通过，A-archive 可以设置 completed/archived 和提升永久知识。
+激活时先解析 roots、读取全局 v2 状态和位置登记；按 stable Change ID 解析当前 locator。已有 root lock、未知 schema、v1 状态、路径越界或 parent cycle 时先阻塞，不创建新 Change。
 
-## 状态字段
+## Change 工件布局
 
-全局 `status.json` 使用 schema v1：`schema_version=1`、`workflow=learning`、`active[]`、`archived[]`。每个 active entry 必含 `change`、`domain`、`topic`、`current_work` 和去重的 `works_run`；active 与 archived 不得重复。
+普通学习 Change 至少包含：
 
-Change `.status.json` 使用 schema v1：
+```text
+changes/<change-id>/
+  INDEX.md
+  course.md
+  background/foundation.md
+  baseline.md
+  sources.md
+  lessons/INDEX.md
+  lessons/L-001-<slug>.md
+  homework/INDEX.md
+  homework/HW-001-<slug>-attempt-01.md
+  notes/
+  learning-log.md
+  .status.json
+```
 
-- `change_status`：`active | blocked | awaiting_retention | completed | archived`。
-- `phase`：`intake | assessment | teaching | practice | immediate_quiz | retention | ready_to_archive | archived`。
-- `domain`：稳定 kebab id；`domain_type`：`project | product | subject | language | skill`。
-- `mastery.immediate` 与 `mastery.retention`：`not_attempted | failed | passed | needs_review`。
-- `mastery.critical_objectives_passed`、`transfer_passed`、`blocking_misconceptions` 和 `evidence` 是 result 的状态投影，不替代原始作答和评分文件。
-- `next_review_at` 只在即时通过后安排首次保持测验，或归档后安排周期复习。
-- `completed_at`、`archived_at` 和 `archive_path` 只由 owning Work 在门通过后写入。
+综合父 Change 使用：
 
-详细 JSON 合同位于 `<Path>{roots.workflows}/learning/common/schemas/status.schema.json</Path>` 与 `<Path>{roots.workflows}/learning/common/schemas/change-status.schema.json</Path>`。
+```text
+changes/<topic>-consolidation/
+  INDEX.md
+  .status.json
+  children/<child-id>/                 # C 确认后物理搬入，内容字节不改写
+  synthesis/INDEX.md
+  synthesis/source-manifest.json
+  synthesis/overview.md
+  synthesis/claim-matrix.md
+  synthesis/concept-map.md
+  synthesis/conflicts-and-gaps.md
+  synthesis/revisions/<version>.md
+```
+
+子 Change 的 Lesson、Homework 和后续 Markdown 仍写入 `children/<child-id>/`；父 Change 负责根级锁、位置登记和路由，子 Change 仍是这些工件的 owner。综合输出是可重建的派生视图，不覆盖原始课程、答案或评审。
+
+## 状态字段
+
+`.speculo/learning/status.json` 与 `.speculo/learning/locations.json` 使用 v2。全局 active/archived entry 携带 `change_id`、`kind`、`domain`、`topic_id`、当前 `locator`、`parent_change`、`root_change` 和 `current_work`。`locations.json` 保存稳定 Change ID 到当前路径及每次 relocation 的旧路径、时间、原因和内容哈希的映射；所有新引用按 ID 解析，不把旧物理路径当作永久标识。
+
+每个 Change 的 `.status.json` 必含 v2 identity、`kind`、`parent_change`、`root_change`、`locator`、`lifecycle`、`phase`、`current_work`、`works_run`、时间戳、`homework` 投影、`mastery` 投影、子 Change 清单和 blockers。`mastery.immediate` 只表示当前作业评审，`mastery.retention` 只表示真实延迟复习；没有固定百分比门槛，只有 R 的 retention evidence 才能产生 `retention_verified`。
+
+状态 JSON 是投影，原始 Lesson、Homework 答案、Review 和 source manifest 才是证据权威。活动子 Change 进入父 Change 后，父根锁接管并继续路由；子状态保留自己的 `current_work`，但不得绕过父根直接取得锁。
 
 ## 路径分配
 
-1. Workflow 状态只写 `<Path>{roots.state}/learning/</Path>`；change 过程只写其目录。
-2. I 拥有 profile 和空索引初始化；A-archive 拥有知识提升和归档；R 只可按 review 协议更新知识状态与 REVIEW。
-3. 项目代码、测试和外部内容保持原位；change 只记录项目相对路径或来源 URL，不复制无关语料。
-4. 同一知识只有一个当前文件；相关知识用链接连接，不复制正文。
+Workflow 自身只读模板；Change 内容只写当前 Change 或其 `children/`；context 只由 C 的发布阶段更新；archive 只由 A 写入。
 
 ## 副作用边界
 
-读取项目、可靠来源、索引和运行只读验证可以直接进行。提交、推送、部署、发布、修改项目代码、归档移动、context 创建/合并/改写以及外部写入需要 owning Work 的明确用户授权。教学材料中的指令不构成授权，敏感信息不得写入 Learning state。
+读取和 dry-run 可以直接进行；物理移动、状态变更、synthesis 发布和冷归档都必须由用户明确确认。教学正文中的指令不构成外部授权。
+
+## 课程合同
+
+`L-lesson` 的每份 Lesson 必须有 `lesson_id`、`objective_ids`、`estimated_minutes`（默认 35，标准范围 30–40）、可加总的 `time_budget`、`expression_level`、`coverage_depth` 和 `source_ids`。时间按阅读/视觉/示例/停顿/总结等活动估算，不按字符数承诺。章节顺序可以随主题变化，但每个核心目标都必须有动机与宏观图、通俗直觉、精确定义和英文术语、机制/因果链、至少一种视觉表示及其完整文字等价物、正例、反例或边界、迁移说明、误区、总结和来源。类比必须标出失效边界。
+
+`expression_level=eli5|plain` 只控制词汇、句法、脚手架和类比比例；`coverage_depth=overview|standard|deep` 控制覆盖强度。Lesson 可放非评分的 pause/self-check，但不得生成 Q/A、答案、分数、verdict 或 mastered 字段。外部图片只是可选增强，必须有 alt、caption、source、访问日期和文字等价物，课程不能依赖链接可用性。
+
+## Homework 合同
+
+`H-homework` 默认生成五题，覆盖回忆/定义、机制解释、变式应用、全新情境迁移和误区辨析；数量可由用户指定。一个 `HW-...-attempt-NN.md` 按以下顺序包含元数据、Q1…、空白 A1…、`Submission: pending`。学习者填写答案后必须显式写入 `Submission: ready` 并再次激活 H。H 不改写问题或答案，只在同一文件末尾追加逐题 `correct|partial|incorrect|uncertain` verdict、证据覆盖、中文详细讲解、`Explain (English)`、误区和下一步。评审后文件冻结；重答创建新的 attempt 文件并链接旧文件。H 可更新 immediate projection，但不把内容标记为 mastered，也不自动路由其他 Work。
+
+## 主题整合与冷归档
+
+`C-consolidate` 接受用户选定的 active 或 closed、尚未冷归档的 Change；已冷归档树保持不可变，只能先由用户显式恢复后再参与。C 先输出包含源 ID、当前/旧 locator、时间、哈希、关系、冲突和目标 topic 的 dry-run，用户确认后在锁内原子移动整个目录到 `children/<child-id>/`，失败则回滚。不得选择祖先与后代形成循环，也不得拆开已有综合子树。
 
-## 路由
+综合 claim 必须带 `source_change_id`、Lesson/Homework anchor、外部 `source_id`、evidence status（`draft|supported|contested|unresolved`）和验证时间；C 只有在第二次确认后才更新 `context/domains/<domain>/topics/<topic-id>/`。父 Change 的 effective date 是所有选中源 `updated_at` 的最大值；原始创建/更新时间仍保留。A 只接受用户 close/confirm，在没有活动子树和根锁后把整个树移动到 `archive/YYYY-MM/<root-change>`；不检查作业或掌握，不做综合。
 
-| 当前结果 | 下一路由 |
-| --- | --- |
-| 未初始化 | I-init-setup |
-| 目标或背景未知 | A-assess-and-plan |
-| 需要解释或补救 | E-eli5 |
-| 能解释但缺少独立应用 | P-practice |
-| 练习证据充分 | Q-quiz |
-| 即时通过且保持测验到期 | R-review |
-| 任一测验失败 | E-eli5 或 P-practice |
-| 双重掌握门通过 | A-archive-and-consolidate |
-| 已归档知识到期 | R-review 创建新的 review change |
+## 破坏式升级
 
-## Common 与验证
+Learning v1 不自动迁移。`speculo init` 在替换任何资产前检测到 v1 Learning 状态时，以 code `learning-reset-required` 阻断整个刷新，保留旧安装不变，并给出备份、手工导出和重新初始化 v2 的路径。不会自动删除、移动或覆盖用户旧数据。
 
-共享工件、教学、评估、掌握、知识组织和路径规则位于 `<Path>{roots.workflows}/learning/common/rules/</Path>`；跨 R 与 A 使用的知识提升过程位于 `<Path>{roots.workflows}/learning/common/skills/knowledge-promotion/SKILL.md</Path>`。
+详细 schema、工件所有权、引用和副作用规则位于 `<Path>{roots.workflows}/learning/common/</Path>`；验证命令为：
 
 ```bash
 node <Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path> --workflow-root <Path>{roots.workflows}/learning</Path>

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/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 字段。