@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/learning/learning-h-homework/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: learning-h-homework
+description: "以单一 Markdown 文件生成题目、接收显式提交并追加逐题评审；不与 Lesson 混写。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/homework
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 课程作业与评审
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+1. 用户指定一个或多个 Lesson/OBJ 和题数（默认 5）。按 Lesson/OBJ 索引只读取对应课程正文、目标、来源和背景；不得把题目答案提前写入作业。
+2. 创建 `homework/HW-<NNN>-<slug>-attempt-01.md`，写元数据、Q1…、空白 A1… 和 `Submission: pending`，更新 `homework/INDEX.md`。
+3. 用户填写 A1…并在文件中加入精确行 `Submission: ready` 后再次激活 H。H 校验回答原文和提交标记，冻结问题/答案内容。
+4. 只在同一文件末尾追加 `## Review`：每题给出 `correct|partial|incorrect|uncertain`、证据覆盖、中文详细讲解、`Explain (English)`、误区和下一步，并记录引用的 Lesson/source anchor。
+5. 评审完成后更新 homework/immediate 投影；不写 mastered、不自动启动 R/C/A。重新作答必须创建新的 attempt 文件并链接旧 attempt，旧文件不可改写。
+
+## 完成标准
+
+- 一个作业文件包含问题、学习者答案、提交标记和 AI 评审；
+- 评审不会改写学习者答案，答案不完整时按 evidence/uncertain 处理；
+- H 的分类结论可结束当前学习轮次，R 才是延迟掌握证据。
+
+## 子文件
+
+- 作业模板：`<Path>{roots.workflows}/learning/learning-h-homework/assets/homework-template.md</Path>`
+- 评审规则：`<Path>{roots.workflows}/learning/common/rules/assessment-policy.md</Path>`

package/template/workflows/learning/learning-i-init-setup/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: learning-i-init-setup
+description: "初始化 Learning v2 的教学偏好、空索引、位置登记和可验证状态。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/init-setup
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 初始化学习系统
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+1. 读取 `<Path>{roots.state}/learning/status.json</Path>`。不存在时从 `_state/status.json` 原子创建；存在 v1 或未知 schema 时停止并返回 `learning-reset-required`，不修复旧文件。
+2. 读取 `<Path>{roots.workflows}/learning/learning-i-init-setup/assets/learner-profile-template.md</Path>`。只询问无法从环境发现的语言、表达基线、深度、图像/图解偏好、默认 Lesson 时长、Homework 题数和 R 偏好；保留已有字段。
+3. 首次初始化才创建缺失的 `changes/`、`archive/`、`context/domains/`、`locations.json`、`context/INDEX.md`、`context/REVIEW.md`。已有文件先验证并保留，不能重置 active、位置、课程、原答、掌握证据或知识内容；必要文件缺失且存在既有 Change 时报告不一致，不用空索引掩盖。
+4. 运行 `<Path>{roots.workflows}/learning/common/tools/validate-learning.mjs</Path>` 的 state 校验并重读新文件。
+
+## 完成标准
+
+- 状态、位置登记和 profile 是合法 v2；
+- 首次空初始化没有虚构 active Change 或 mastered 条目；复核既有系统时原有记录与用户偏好保持不变；
+- 本次没有外部副作用；新建空索引或既有索引均可导航，后续 Work 可恢复。
+
+## 子文件
+
+- Profile：`<Path>{roots.workflows}/learning/learning-i-init-setup/assets/learner-profile-template.md</Path>`
+- 总目录：`<Path>{roots.workflows}/learning/learning-i-init-setup/assets/context-index-template.md</Path>`
+- 复习目录：`<Path>{roots.workflows}/learning/learning-i-init-setup/assets/review-index-template.md</Path>`

package/template/workflows/learning/learning-l-lesson/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: learning-l-lesson
+description: "一次输出 30–40 分钟、通俗但完整的 Lesson；不生成作业、不评分、不宣称掌握。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/lesson
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 完整课程讲解
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/lesson-contract.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>`；只有工程、Agent 或外部工具主题读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.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/learning-l-lesson/assets/lesson-template.md</Path>`
+- 教学规则：`<Path>{roots.workflows}/learning/common/rules/teaching-policy.md</Path>`
+
+仅编译独立网页课程时读取 `<Path>{roots.workflows}/learning/common/rules/portable-learning-runtime.md</Path>`；本地仍保留 A 产物前置条件，不加载网页适配。

package/template/workflows/learning/learning-l-lesson/assets/lesson-template.md

@@ -0,0 +1,55 @@
+---
+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
+
+### 机制/因果链
+
+### 图、表或文本图
+
+图后必须有完整的文字等价物和图的边界说明。
+
+### 正例、反例与边界
+
+## 变式与迁移
+
+## 常见误区
+
+## 潜在盲区与现实检验
+
+选择与目标相关的主要遗漏，说明为何容易忽略、影响什么判断、反例/失败机制，以及处理边界和验证设计。区分潜在盲区与已证明的理解偏差；不生成学习者 Q/A，不声称执行了未运行的测试。
+
+## 非评分暂停
+
+## 总结、词汇表与下一步
+
+## 来源与引用
+
+| Source ID | 来源 | 支持的 claim/段落 | 定位 | 访问日期 |
+| --- | --- | --- | --- | --- |
+| S-001 | `<title and URL>` | `<claim>` | `<page/section>` | `<YYYY-MM-DD>` |

package/template/workflows/learning/learning-q-question/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: learning-q-question
+description: "tutor 默认约 5 题、作答后讲解；explore 主动发现盲区并深入到处理与验证。无 Change 可创建轻量主题；两种模式不混写，不自动串联 L/H/R。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/question
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 深度探究与苏格拉底问答课
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题和证据 ID 定位最小输入，不默认整读 context/archive。
+
+两种模式均读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/question-map-contract.md</Path>`。只有工程、Agent 或外部工具主题读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。
+
+<!-- portable:question:start -->
+## 模式选择
+
+`mode=tutor|explore` 与 `teaching_method` 是不同维度。显式 mode 优先；恢复时未指定则沿用当前工件模式；新任务要求“考我、让我先答、苏格拉底练习”时使用 tutor，要求“替我主动挖掘、找出未提出的问题、直接深入讲解”时使用 explore；其余默认 tutor。既希望深挖又希望自己回答时仍可用 tutor 加强内容深度，不必强制切换模式。
+
+tutor 保持先作答后讲解，一批默认 5 题，用户指定正整数 n 则生成 n 对连续 Q/A，不能截断或套用其他模式上限。explore 直接发现、解释和推演，不伪造学习者答案、提交状态或理解表现。两种方式都要解释重要发现的原因，并推进主要分支到证据与验证。
+
+已有未提交问答批次时要求直接探索，另建探索记录并关联原问题，保留原始批次及提交状态；不能替学习者填 A、自动提交或原地改成自问自答。恢复请求没有提供可定位的权威工件时，先找本主题实际记录，不能虚构上次进度。
+<!-- portable:question:end -->
+
+## 共同启动
+
+1. 解析 roots 与 Learning v2 状态、stable Change ID、当前 locator 和根锁。缺少 status.json/locations.json 时按 I-init-setup 初始化空骨架；未知 schema、v1、锁冲突、越界或 parent cycle 按激活合同阻塞。任何状态写入仍须满足入口授权。
+2. 没有可用 Change 时，按用户主题创建 lightweight inquiry Change `YYYY-MM-DD-<kebab-topic>`：INDEX.md、最小 course.md/baseline.md/sources.md、inquiry/INDEX.md、learning-log.md 和 .status.json（phase=teaching，current_work=learning/question）。不假装完成完整课程设计。轻量模板读取 `<Path>{roots.workflows}/learning/learning-q-question/assets/lightweight-course-template.md</Path>`。
+3. 已有 Change 时只取对应 course/OBJ/Lesson/baseline/notes 和 inquiry 索引相关项；问题地图首次使用才创建，不回填旧历史。恢复已关闭记录只读，后续建立新批次或探索。
+4. 按上方规则选模式并只加载对应分支。`mode=tutor` 读取 `<Path>{roots.workflows}/learning/learning-q-question/references/tutor-mode.md</Path>`；`mode=explore` 读取 `<Path>{roots.workflows}/learning/learning-q-question/references/exploration-mode.md</Path>`。不要同时执行两个分支。
+
+## 工件与完成边界
+
+- tutor 使用 inquiry/IQ-*.md：Response: pending → ready → closed，冻结原 Q/A 后追加 Teaching 与 Inquiry Lesson；完整协议及 validate-inquiry 命令在 tutor 分支。
+- explore 使用 inquiry/explorations/EX-*.md 与 inquiry/question-map.json；独立结构验证，不送入 IQ 的提交状态机。
+- Q 只拥有当前 Change 的 inquiry/ 及已授权的索引、日志、状态更新；不写 lessons/、homework/、goal/、mastery 或永久 context，不自动激活 L/H/R/G。
+- 问题地图的 resolved 不表示 mastered；只有真实延迟复习证据才能由原 owner 更新 retention。结构验证不认证教学质量。
+- 先验证工件与引用、发布工件，再更新索引/日志和 Change 状态。失败保留候选与恢复证据，不提前清空 blocker 或推进完成。
+
+## 网页适配
+
+仅编译独立网页能力时读取 `<Path>{roots.workflows}/learning/common/rules/portable-learning-runtime.md</Path>`；工作区执行不加载该适配，不改变原 Response 精确行协议。

package/template/workflows/learning/learning-q-question/assets/exploration-template.md

@@ -0,0 +1,28 @@
+---
+exploration_id: EX-001-topic
+mode: explore
+status: active
+question_ids: [P-001]
+---
+
+# 主动探究记录
+
+## Scope
+
+写明原问题、目标、材料范围、事实与假设；不把教学情境当成已经发生的故障。
+
+## Discovery
+
+按问题 ID 给出发现、为何容易遗漏、为什么重要，以及父问题/触发证据。只列相关方向，不凑配额。
+
+## Deep Dive
+
+主要分支讲清机制、反例、所需证据、方案与代价；工程问题说明处理责任层。
+
+## Verification
+
+区分验证设计、已取得证据、实际测试记录和仍未验证的结论。写出输入、可观察结果与通过条件。
+
+## Next
+
+记录停止原因、待证据/暂缓项和一个可选后续。不得把当前轮关闭等同于全部问题解决或学习者已掌握。

package/template/workflows/learning/learning-q-question/assets/inquiry-template.md

@@ -0,0 +1,75 @@
+---
+inquiry_id: IQ-<NNN>
+batch: 01
+lesson_unit_id: IQ-<NNN>
+objective_ids: [OBJ-01]
+question_count: 5
+teaching_method: socratic
+expression_level: plain
+coverage_depth: standard
+source_ids: [S-001]
+created_at: <ISO-8601>
+---
+
+# 苏格拉底问答课：<主题>
+
+<!-- 下方五组是默认示例。生成时以本批实际 n 替换 question_count，并生成连续配对的 Q1…Qn/A1…An；不得把用户指定数量截断为五题。 -->
+
+## 引用
+
+- Change：`<stable change id and current locator>`
+- 目标：`<OBJ ids>`
+- 教法：`socratic | 5e-recipe | feynman | productive-failure | custom`
+- Skill：`socratic-questioning`
+
+## 问题来源
+
+本批每题关联问题地图 ID、父问题或触发证据，简述为什么值得问但不泄露目标答案。新题来自相关盲区、前一批回答或新情境；复问注明理由。
+
+## Questions
+
+### Q1 — 澄清与定义
+
+<问题>
+
+### Q2 — 机制与证据
+
+<问题>
+
+### Q3 — 假设与反例
+
+<问题>
+
+### Q4 — 迁移与视角
+
+<问题>
+
+### Q5 — 元问题与下一步
+
+<问题>
+
+## Learner Answers
+
+### A1
+
+<在此填写，不要改写 Q1>
+
+### A2
+
+<在此填写，不要改写 Q2>
+
+### A3
+
+<在此填写，不要改写 Q3>
+
+### A4
+
+<在此填写，不要改写 Q4>
+
+### A5
+
+<在此填写，不要改写 Q5>
+
+Response: pending
+
+<!-- Q 在 Response: ready 后只能追加 Teaching 与 Inquiry Lesson；不得改写以上内容。不得使用 Submission 或 verdict。 -->

package/template/workflows/learning/learning-q-question/assets/question-map-template.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "questions": []
+}

package/template/workflows/learning/learning-q-question/references/exploration-mode.md

@@ -0,0 +1,35 @@
+# Explore 主动探究分支
+
+仅 `mode=explore` 时读取；入口已经完成 Learning v2 激活、stable Change ID、locator、锁及授权检查。本分支不调用 socratic skill 的 tutor/mine 协议。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/question-map-contract.md</Path>`；工程主题才读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。输出模板是 `<Path>{roots.workflows}/learning/learning-q-question/assets/exploration-template.md</Path>`。
+
+<!-- portable:explore:start -->
+## 主动探究方式
+
+适用于用户明确要求主动挖掘、发现未提出的问题、分析实际失败或直接深入讲解。默认先回应核心问题，再给出有理由的重点发现，展开最值得处理的分支。无需等待学习者完成所有题目；不伪造学习者答案，也不把 AI 自问自答作为学习者表现。
+
+先限定主题、已有材料、目标和证据范围。缺少非关键背景时用明确假设推进；关键证据缺失只阻塞依赖该证据的结论。初学者先补必要模型，不用大量反问掩盖未解释的概念。用户明确指定问题数量时尊重该数量；没有指定则按相关性和本轮范围选择，不套用固定五题或源码挖掘上限。
+
+形成发现清单：潜在盲区/已观察的偏差、为何遗漏、为什么重要、父问题或触发证据。主要分支按机制、证据、方案/代价、验证与边界展开。其他分支明确标注待证据或暂缓，不假装已经处理。
+
+使用独立探索记录，依次包含 `## Scope`、`## Discovery`、`## Deep Dive`、`## Verification`、`## Next`。元数据有 `exploration_id`（`EX-001-topic` 形式）、`mode: explore`、`status: active|blocked|closed`、非空 `question_ids` 列表。关联问题写入问题地图；每个 focus ID 必须属于本记录。
+
+Next 说明本轮停止原因、未解决项与可选后续；不自动开展新批次或其他任务。active 可继续补充；blocked 保留缺失证据与恢复条件；closed 是本轮结束，不是学习者掌握。关闭时 focus 问题必须已 resolved、needs_evidence 或 deferred。关闭后重新探索需新记录与父问题链接。
+<!-- portable:explore:end -->
+
+## 工作区落盘与验证
+
+仅写当前 Change 的 `inquiry/explorations/EX-<NNN>-<slug>.md`、`inquiry/question-map.json`，以及已授权的 `inquiry/INDEX.md`、`learning-log.md` 和 Change 状态。不写 `lessons/`、`homework/`、`goal/`、mastery 或永久 context；不出现 learner `Response:`、`Submission:`、Q/A 和 verdict 协议字段。
+
+候选记录与候选地图先在当前 Change 的 `inquiry/` 暂存；地图 artifact 仍指向正式目标，通过 `--artifact` 指明。不得先覆盖正式地图再校验。验证命令：
+
+```bash
+node <Path>{roots.workflows}/learning/learning-q-question/scripts/validate-exploration.mjs</Path> --change-dir <当前Change绝对路径> --file <候选记录相对路径> --map <候选地图相对路径> --artifact <正式记录相对路径>
+```
+
+用户明确指定问题数量 n 时附加 `--expected-count <n>`，不得以默认重点数量截断；未指定时不填该参数。
+
+全部验证成功后，在原有根锁下重读基线，依次发布记录、地图、索引/日志，再更新 Change `.status.json`（phase 仍为 teaching，works_run 包含 learning/question，完成本次调用后清空 current_work）。若中途失败保留候选与恢复说明，不推进状态；工件/地图冲突时只阻塞相关写集，不猜测赢家。没有现成写权限时先取得入口要求的确认。
+
+恢复时用稳定 ID 解析当前位置，先读本记录和地图相关 ID，再取少量权威证据；不遍历整棵历史。新结构不要求迁移 Learning v2 或改写旧 IQ。验证器只检查结构、引用、路径和提供的证据文件是否存在，不认证分析质量、用户理解或测试内容真实性。

package/template/workflows/learning/learning-q-question/references/tutor-mode.md

@@ -0,0 +1,31 @@
+# Tutor 问答课分支
+
+仅 mode=tutor 时读取；共同启动、锁、稳定 Change ID 和授权由 Q 入口完成。此分支保留现有学习者提交协议，explore 不使用本分支。
+
+## 出题与授课
+
+1. 读取 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>`、`<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>` 与 `<Path>{roots.workflows}/learning/learning-q-question/assets/inquiry-template.md</Path>`。选择用户教法或默认 socratic；用户指定正整数 n 则使用该值，否则 5，不套用 mine 十问上限。
+2. 依共享深挖规则从相关遗漏、前一批回答或新证据选择问题，在题目旁给简短、不泄露目标答案的关注理由。每题关联问题地图 ID；地图只登记新问题，不迁移历史。创建 inquiry/IQ-<NNN>-<slug>-batch-NN.md：question_count=n、Q1…Qn、空 A1…An、精确行 Response: pending。不得把答案写入题目。
+3. 学习者填写 A1…并写入精确行 Response: ready 后再次激活。校验并冻结原始元数据、Q/A。没有 ready 不追加 Teaching / Inquiry Lesson；不以模型自述或推测替代用户提交。
+4. 只在同一文件末尾追加 ## Teaching 和 ## Inquiry Lesson。Teaching 逐题给思路复原、aligned|partial|off|uncertain、中文详解、Explain (English)、纠错路径、先前未覆盖知识及其重要原因、来源锚点和验证思路。Inquiry Lesson 将实际 n 题收成一节短课，留下基于新证据的下一批种子或可选补课/作业/复习入口。Response 更新为 closed。没有证据不能宣布用户掌握。
+5. 更新 inquiry/INDEX.md、问题地图、learning-log.md 和 Change .status.json；works_run 追加 learning/question，清空 current_work。不写 mastered、lessons/ 或 homework/，不自动激活其他 Work。重答新建批次并链接旧文件；记录 revisit_reason，不改写旧批次。
+
+## 当前批次验证
+
+生成新批次后，以实际用户数量 n 运行：
+
+```bash
+node <Path>{roots.workflows}/learning/learning-q-question/scripts/validate-inquiry.mjs</Path> --change-dir <当前Change绝对路径> --file <当前批次相对路径> --expected-count <n>
+```
+
+关闭前在当前 Change 内保留用户已提交的 Response: ready 原文快照，以候选 closed 文件和 --before <ready快照相对路径> 校验元数据及 Q/A 字节不变，再发布。快照是本批证据，不建立第二套状态树。失败不更新 Response 或状态；归档或合并的 Change 按稳定 ID 解析当前 locator，不硬编码 changes/ 位置。
+
+新建地图使用 `<Path>{roots.workflows}/learning/learning-q-question/assets/question-map-template.json</Path>`。批次结构验证并发布后，验证尚未发布的候选地图：
+
+```bash
+node <Path>{roots.workflows}/learning/learning-q-question/scripts/validate-exploration.mjs</Path> --change-dir <当前Change绝对路径> --map <候选地图相对路径>
+```
+
+地图引用真实已发布 IQ，验证成功后发布地图再更新索引/日志/状态；失败保留有效 IQ 和候选地图，报告恢复路径，不提前推进状态。验证器只证明提供的原文字节/结构与路径，不认证回答作者、内容正确性或授课质量。
+
+Teaching 不是作业评分 Review，不使用 Submission 或 verdict: correct|partial|incorrect。完整 30–40 分钟讲义仍归 L；真新手或高元素交互时使用降级探针或建议先补课，不强制硬答。

package/template/workflows/learning/learning-q-question/scripts/validate-exploration.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/** Read-only structure/reference gate. It does not certify learning, truth or test authenticity. */
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => typeof v === 'string' && v.trim().length > 0;
+const problemId = /^P-\d{3,}$/;
+const explorationId = /^EX-\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const statuses = new Set(['open', 'exploring', 'resolved', 'needs_evidence', 'deferred']);
+const evidenceStates = new Set(['unverified', 'supported', 'tested']);
+const learnerFields = new Set(['mastered', 'mastery', 'retention_verified', 'verdict', 'response', 'submission']);
+const scope = 'structure, graph and supplied references only; not teaching quality, mastery or test authenticity';
+
+export function safeRelative(value) {
+  return text(value) && !isAbsolute(value) && !/^[A-Za-z]:/.test(value) &&
+    !/[\\\x00-\x1f\x7f]/.test(value) && !value.split('/').some((p) => !p || p === '.' || p === '..');
+}
+function artifactPath(value) {
+  return safeRelative(value) && /^inquiry\/(?:IQ-\d{3,}-[a-z0-9-]+|explorations\/EX-\d{3,}-[a-z0-9-]+)\.md$/.test(value);
+}
+
+export function validateQuestionMap(map) {
+  const errors = [];
+  if (!object(map) || map.schema_version !== 1 || !Array.isArray(map.questions)) {
+    return { valid: false, errors: ['question map requires schema_version=1 and questions array'], scope };
+  }
+  const byId = new Map();
+  for (const q of map.questions) {
+    if (!object(q)) { errors.push('question must be an object'); continue; }
+    const label = text(q.id) ? q.id : 'question';
+    if (typeof q.id !== 'string' || !problemId.test(q.id) || byId.has(q.id)) errors.push(`${label}: invalid or duplicate id`);
+    else byId.set(q.id, q);
+    if (!(q.parent_id === null || (typeof q.parent_id === 'string' && problemId.test(q.parent_id)))) errors.push(`${label}: invalid parent_id`);
+    if (!new Set(['user', 'answer', 'material', 'inference']).has(q.origin)) errors.push(`${label}: invalid origin`);
+    for (const key of ['trigger', 'dimension', 'why_it_matters', 'verification']) if (!text(q[key])) errors.push(`${label}: ${key} is required`);
+    if (typeof q.conclusion !== 'string') errors.push(`${label}: conclusion must be a string`);
+    if (!new Set(['potential', 'observed']).has(q.gap_kind)) errors.push(`${label}: invalid gap_kind`);
+    if (!statuses.has(q.status)) errors.push(`${label}: invalid problem status (not mastery)`);
+    if (!evidenceStates.has(q.evidence_status)) errors.push(`${label}: invalid evidence_status`);
+    if (!Array.isArray(q.evidence) || q.evidence.some((e) => !text(e))) errors.push(`${label}: evidence must be an array of locators`);
+    const hasEvidence = Array.isArray(q.evidence) && q.evidence.some(text);
+    if ((q.gap_kind === 'observed' || q.evidence_status === 'supported' || q.evidence_status === 'tested') && !hasEvidence) errors.push(`${label}: evidence locators are required`);
+    if (q.status === 'resolved' && (!text(q.conclusion) || q.evidence_status === 'unverified')) errors.push(`${label}: unresolved evidence cannot be marked resolved`);
+    if (!artifactPath(q.artifact)) errors.push(`${label}: artifact must be an owned inquiry path`);
+    if (q.revisit_reason !== undefined && !text(q.revisit_reason)) errors.push(`${label}: revisit_reason cannot be empty`);
+    if (q.evidence_status === 'tested' && !(safeRelative(q.test_evidence) && q.test_evidence.startsWith('inquiry/evidence/'))) errors.push(`${label}: tested requires an inquiry/evidence/ record`);
+    if (q.test_evidence !== undefined && !(safeRelative(q.test_evidence) && q.test_evidence.startsWith('inquiry/evidence/'))) errors.push(`${label}: unsafe test_evidence`);
+    if (Object.keys(q).some((key) => learnerFields.has(key.toLowerCase()))) errors.push(`${label}: learner assessment fields are not allowed`);
+  }
+  for (const [id, q] of byId) if (q.parent_id !== null && !byId.has(q.parent_id)) errors.push(`${id}: parent is missing`);
+  // Iterative traversal avoids recursion/stack limits for long, valid histories.
+  const visited = new Set();
+  for (const id of byId.keys()) {
+    const chain = new Set(); let current = id;
+    while (current !== null && byId.has(current) && !visited.has(current)) {
+      if (chain.has(current)) { errors.push(`${id}: parent cycle`); break; }
+      chain.add(current); current = byId.get(current).parent_id;
+    }
+    for (const item of chain) visited.add(item);
+  }
+  return { valid: errors.length === 0, errors, scope };
+}
+
+function visible(markdown) {
+  let fence = null;
+  return markdown.replace(/<!--[\s\S]*?(?:-->|$)/g, '').split(/\r?\n/).map((line) => {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+    if (!fence && marker) { fence = marker; return ''; }
+    if (fence) { if (/^\s*(`{3,}|~{3,})[ \t]*$/.test(line) && marker && marker[0] === fence[0] && marker.length >= fence.length) fence = null; return ''; }
+    return line;
+  }).join('\n');
+}
+
+export function validateExploration(markdown, map, { artifact, expectedCount } = {}) {
+  const result = validateQuestionMap(map), errors = [...result.errors];
+  const fail = (message) => { errors.push(message); };
+  if (typeof markdown !== 'string') return { valid: false, errors: [...errors, 'exploration must be Markdown text'], scope };
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!match) return { valid: false, errors: [...errors, 'exploration frontmatter is required'], scope };
+  const fields = new Map();
+  for (const line of match[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const field = /^([a-z][a-z0-9_]*):[ \t]*(.*?)[ \t]*$/.exec(line);
+    if (!field || fields.has(field[1])) { fail('invalid or duplicate exploration metadata'); continue; }
+    if (learnerFields.has(field[1]) || /^[qa]\d+$/.test(field[1])) fail('explore metadata must not contain learner answer/assessment protocol');
+    fields.set(field[1], field[2]);
+  }
+  const id = fields.get('exploration_id'), status = fields.get('status');
+  if (!explorationId.test(id ?? '')) fail('invalid exploration_id');
+  if (fields.get('mode') !== 'explore') fail('mode must be explore');
+  if (!new Set(['active', 'blocked', 'closed']).has(status)) fail('invalid exploration status');
+  const idsValue = fields.get('question_ids') ?? '';
+  const ids = /^\[.*\]$/.test(idsValue) ? idsValue.slice(1, -1).split(',').map((s) => s.trim()) : [];
+  if (!ids.length || ids.some((i) => !problemId.test(i)) || new Set(ids).size !== ids.length) fail('question_ids must be a nonempty unique problem ID list');
+  if (expectedCount !== undefined && (!Number.isSafeInteger(expectedCount) || expectedCount < 1 || ids.length !== expectedCount)) fail('question count differs from user request');
+  const target = artifact ?? `inquiry/explorations/${id}.md`;
+  if (!artifactPath(target) || target !== `inquiry/explorations/${id}.md`) fail('artifact must match exploration_id');
+  const byId = new Map((Array.isArray(map?.questions) ? map.questions : []).filter(object).map((q) => [q.id, q]));
+  for (const problem of ids) {
+    const q = byId.get(problem);
+    if (!q || q.artifact !== target) fail(`${problem}: focus question must belong to this exploration`);
+    if (status === 'closed' && q && !new Set(['resolved', 'needs_evidence', 'deferred']).has(q.status)) fail(`${problem}: closing must dispose of the active focus explicitly`);
+  }
+  const body = visible(markdown.slice(match[0].length));
+  if (/^(?:Response|Submission|mastered|mastery|verdict)\s*:|\bverdict\s*:|^#{1,6}\s+[QA]\d+\b/im.test(body)) fail('explore must not contain learner answer/assessment protocol');
+  const headings = [...body.matchAll(/^## ([^\n]+)\s*$/gm)];
+  const expected = ['Scope', 'Discovery', 'Deep Dive', 'Verification', 'Next'];
+  if (headings.length !== expected.length || headings.some((h, i) => h[1].trim() !== expected[i])) fail('requires ordered Scope, Discovery, Deep Dive, Verification, Next sections');
+  else for (let i = 0; i < headings.length; i++) {
+    const start = headings[i].index + headings[i][0].length, end = headings[i + 1]?.index ?? body.length;
+    if (!text(body.slice(start, end))) fail(`${expected[i]} must not be empty`);
+  }
+  return { valid: errors.length === 0, exploration_id: id ?? null, status: status ?? null, question_count: ids.length, errors, scope };
+}
+
+function inspectWithin(root, value, allowMissing = false) {
+  if (!safeRelative(value) || !value.startsWith('inquiry/')) throw new Error('path must be relative and inside inquiry/');
+  const full = resolve(root, value), rel = relative(root, full);
+  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) throw new Error('path escapes change-dir');
+  if (realpathSync(root) !== root) throw new Error('change-dir must not traverse a symlink');
+  let current = root, stat;
+  const parts = rel.split(sep);
+  for (let i = 0; i < parts.length; i++) {
+    current = resolve(current, parts[i]);
+    try { stat = lstatSync(current); }
+    catch (error) { if (allowMissing && error.code === 'ENOENT') return { full, exists: false }; throw error; }
+    if (stat.isSymbolicLink()) throw new Error('inquiry symlinks are not permitted');
+    if (i < parts.length - 1 && !stat.isDirectory()) throw new Error('inquiry parent must be a directory');
+  }
+  if (!stat?.isFile()) throw new Error('inquiry reference must be a regular file');
+  return { full, exists: true };
+}
+function readWithin(root, value) {
+  return readFileSync(inspectWithin(root, value).full, 'utf8');
+}
+function protectPublished(root, target, candidate) {
+  const destination = inspectWithin(root, target, true);
+  if (!destination.exists) return;
+  const before = readFileSync(destination.full, 'utf8');
+  const header = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(before)?.[1];
+  const fields = new Map();
+  for (const line of (header ?? '').split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const field = /^([a-z][a-z0-9_]*):[ \t]*(.*?)[ \t]*$/.exec(line);
+    if (!field || fields.has(field[1])) throw new Error('published exploration metadata conflict; recover before replacing');
+    fields.set(field[1], field[2]);
+  }
+  if (!header || !new Set(['active', 'blocked', 'closed']).has(fields.get('status')) || fields.get('mode') !== 'explore' ||
+      `inquiry/explorations/${fields.get('exploration_id')}.md` !== target) throw new Error('published exploration metadata conflict; recover before replacing');
+  if (fields.get('status') === 'closed' && before !== candidate) throw new Error('closed exploration is read-only; create a linked new record');
+}
+
+export function run(args) {
+  const flags = new Map();
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i], value = args[i + 1];
+    if (!['--change-dir', '--file', '--map', '--artifact', '--expected-count'].includes(key) || flags.has(key) || !value || value.startsWith('--')) throw new Error('invalid, duplicate or missing option');
+    flags.set(key, value);
+  }
+  if (!flags.has('--change-dir') || !isAbsolute(flags.get('--change-dir')) || !flags.has('--map')) throw new Error('requires --change-dir ABSOLUTE_CHANGE --map RELATIVE_JSON [--file RELATIVE_MD --artifact FINAL_MD --expected-count N]');
+  if (!flags.has('--file') && (flags.has('--artifact') || flags.has('--expected-count'))) throw new Error('artifact/count require --file');
+  const root = resolve(flags.get('--change-dir'));
+  const mapPath = flags.get('--map');
+  if (!mapPath.endsWith('.json')) throw new Error('map must be JSON');
+  const map = JSON.parse(readWithin(root, mapPath));
+  const countValue = flags.get('--expected-count');
+  if (countValue !== undefined && !/^[1-9]\d*$/.test(countValue)) throw new Error('expected-count must be a positive integer');
+  const file = flags.get('--file');
+  if (file && !file.endsWith('.md')) throw new Error('exploration must be Markdown');
+  const candidate = file ? readWithin(root, file) : null;
+  const result = file ? validateExploration(candidate, map, {
+    artifact: flags.get('--artifact'), expectedCount: countValue === undefined ? undefined : Number(countValue),
+  }) : validateQuestionMap(map);
+  if (result.valid) {
+    const current = file ? (flags.get('--artifact') ?? `inquiry/explorations/${result.exploration_id}.md`) : null;
+    if (current) protectPublished(root, current, candidate);
+    for (const q of map.questions) {
+      if (q.artifact !== current) readWithin(root, q.artifact);
+      if (q.test_evidence && !readWithin(root, q.test_evidence).trim()) throw new Error('test evidence record is empty');
+    }
+  }
+  return result;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { const result = run(process.argv.slice(2)); console.log(JSON.stringify(result, null, 2)); process.exitCode = result.valid ? 0 : 1; }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/template/workflows/learning/learning-r-review/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: learning-r-review
+description: "用户主动指定后，用真实时间间隔验证回忆、机制和迁移，并更新 retention evidence。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: learning/review
+  speculo-domain: learning
+  speculo-contract-version: "2"
+---
+
+# 延迟保持与周期复习
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/homework-contract.md</Path>`；只加载本 Work 需要的领域合同。
+
+读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+
+## 流程
+
+1. 用户明确指定 Lesson、Homework、Change 或 topic；按 review/来源索引只读取对应 sources、目标和到期的过去证据。没有真实间隔时只记录 `due_at`，不伪造通过。
+2. 在 Change 的 `review/INDEX.md` 和 `review/RV-<id>.md` 生成新复习记录。题目必须包含延迟回忆、机制/反例和新的迁移情境，不复制刚看过的示例。
+3. 原样保存回答并给出逐项证据；失败只生成补救范围和 `needs_review`，不删除历史、不改写 archived 原文。
+4. 只有通过真实延迟复习才设置 `mastery.retention=passed`、`mastery.overall=retention_verified`，仅更新当前 Change 的 retention 证据与状态投影。永久 context topic view 仍由 `<Path>{roots.workflows}/learning/learning-c-consolidate/SKILL.md</Path>` 通过原发布网关在用户确认后消费该证据并标记 `mastered`；R 不直接写 context，不自动激活 C 或 A。
+
+## 完成标准
+
+- 时间、来源、题目和回答可审计；
+- R 是可选 Work，H 的 immediate 评审可以结束当前学习轮次；
+- 周期复习失败保留原证据并建立新的补救 Change 或 note。
+
+## 子文件
+
+- Review 模板：`<Path>{roots.workflows}/learning/learning-r-review/assets/review-template.md</Path>`
+- Topic 状态规则：`<Path>{roots.workflows}/learning/common/skills/topic-synthesis/SKILL.md</Path>`