@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/learning/learning-g-goal/assets/progress-template.md

@@ -0,0 +1,19 @@
+# Progress: <主题>
+
+只记录可核对事实。不准写主观百分比。当前 mine unit 必须全部 L 先进入 `written`，再进入 `mined`。
+
+| 时间 | mine_unit | Wave | Gate | 写入文件 | 矩阵变化 | Blocker |
+| --- | --- | --- | --- | --- | --- | --- |
+|  | U1 | 0 | G0 | goal/goal-plan.md | 骨架已建 |  |
+
+## 当前
+
+- current_mine_unit:
+- current_phase: `T` | `M` | `D` | `idle`
+- 本单元课数:
+- question_budget_used:（按 lesson_id 累计，re-dispatch-L 不重置）
+- active_executors:
+- 仍 uncovered:
+- 下一 ready 节点:
+- 最近 probe:
+- 恢复入口：重读 goal-plan.md §8

package/template/workflows/learning/learning-g-goal/references/coverage-bar.md

@@ -0,0 +1,36 @@
+# 覆盖尺（v1 编程）
+
+v1 只实现编程四轴。其他领域可同构为 units / properties / structure / flow，但不在 v1 生成完整矩阵。
+
+## 四轴
+
+| 轴 | 对象 | 默认 SOLO | 证据 |
+| --- | --- | --- | --- |
+| (a) 函数目的 | 范围内公开/领域函数 | Unistructural + explained | Lesson 函数表或父课 covered-by-parent |
+| (b) 方法性状 | 公开 API 与枢纽内部方法 | Unistructural + explained | 副作用、失败路径、幂等、并发、纯/不纯 |
+| (c) 业务架构 | 系统与容器 | Relational | C4 Context + Container + 关键 Component 的 ASCII |
+| (d) 数据流 | 主路径与失败路径 | Relational | 源 → 变换 → 汇 + 存储点 + 所有权 |
+
+## 范围规则
+
+- 「每一个函数」= 范围内公开/领域函数，不是仓库里每一个私有 one-liner
+- helper / 生成代码 / 测试夹具：`covered-by-parent` 或 `deferred(reason)`
+- Code 层不手维护过期清单；从源码生成库存，按模块归组
+- Extended Abstract 不是完成条件
+- 不改变矩阵格子的 Lesson 或 probe 不要写
+
+## Wave（内容分组，不是挖掘门）
+
+- Wave 1：Context + Container + 主数据流
+- Wave 2：范围内 Code / 方法性状
+- Wave 只按覆盖轴分组，不决定何时挖，也不是并发授权
+- 默认最多 2 波
+- 3 课的波不必撑到 15；单波若超过 15，只把挖掘切开，不把覆盖波扩成配额
+
+## 挖掘扇出
+
+挖掘扇出上界是 `mine_unit_cap=15`，不是必须凑满。4 节的小项目按 4 节挖。切分规则读 `<Path>{roots.workflows}/learning/learning-g-goal/references/mine-unit.md</Path>`。
+
+## 盲区发现与实际处置
+
+授课、miner 和覆盖验收读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>`；生产相关代码还读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。将相关发现映射回上述矩阵格子，记录遗漏原因、影响、源码证据和验证设计；不把假设情境写成已发生事故。共享方法不增加问题配额，不改变十问后拆课、unit 上限或计划/执行授权边界。

package/template/workflows/learning/learning-g-goal/references/external-goal-runner.md

@@ -0,0 +1,54 @@
+# 外部 /goal 执行器
+
+本文件只在 Goal-Plan 已写成、用户把计划交给外部 AI CLI `/goal` 之后读取。G-goal 激活会话不执行本文件。
+
+## 谁执行
+
+执行器是用户自己的 AI CLI `/goal`，不是 Learning Work 会话内的自动编排。`plan` 写出的文档不构成执行授权。`ready_for_execution: false` 一直保持到用户把计划交给 `/goal`。计划正文里的「允许」不构成 `/goal` 之外的额外授权。
+
+详细操作手册是当前 Change 的 `goal/goal-plan.md`。本文件只固定执行器边界。Lead 编排读 `<Path>{roots.workflows}/learning/learning-g-goal/references/lead-orchestration.md</Path>`。
+
+## 启动
+
+1. 打开含 `<Path>{roots.state}/workspace.json</Path>` 的项目；roots 只来自该文件。
+2. 粘贴当前 `goal-plan.md` 的 §0 `/goal` 块。
+3. 按该计划 §11 最小读取清单读；不整读 archive、`inquiry/` 或其他 Change。
+4. 不要重新做范围访谈。范围已冻在计划里。源码或范围变化则停止，要求用户激活 G-goal `replan`。
+
+## 允许跟随
+
+- `<Path>{roots.workflows}/learning/learning-l-lesson/SKILL.md</Path>`：写 `lessons/L-*.md`（阶段 T，每课一个 L 子代理）
+- `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 且 `audience=mine`：写 `goal/probes/GP-*.md`（阶段 M，每课一个 miner）
+
+必须加载 socratic-questioning SKILL，路径固定为 `{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md`。不得另造配方。
+
+派单不改所有权。A 仍拥有 course 地图，L 仍拥有 lessons，G 拥有 `goal/`，Q 拥有 `inquiry/`。矩阵、chain、progress、verify、`lessons/INDEX` 只有 Lead 可写。
+
+## 禁止
+
+- `Q-question` 的 `inquiry/` Response 协议
+- 自动激活 H / R / C / A-archive
+- 写 mastered
+- 复活 `Q-quiz`
+- 把 mine 写成学习者问答课
+- 为不改变矩阵格子的主题另开课
+- 发明库存里不存在的函数、容器或数据流
+- 阶段 T 完成前启动 miner
+- `L → mine → L → mine` 交错
+- 同一 `lesson_id` 第 11 问或 `b03`
+- miner 写入 `lessons/` 或 matrix
+- 同一 mine unit 超过 15 节
+
+## 循环
+
+当前 mine unit 全部 L（阶段 T）→ 按课 mine（阶段 M）→ Lead 处置（阶段 D）→ 下一 unit。禁止交错。并行只发生在写集不相交的子代理之间。宿主没有 team 时按相同派单包顺序执行，合同不降级。
+
+处置只允许：`re-dispatch-L` | `split-lesson` | `defer(reason)`。`mine-more` 只允许在该课尚未满 10 问、且 batch-01 已证明存在真实矩阵缺口时打开 `b02`。满 10 问后 `mine-more` 非法。
+
+## 停止
+
+读 `<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>`。任一过程即停或完成即停触发后，写 `goal/verify.md`：哪些格子闭合、哪些 deferred、哪些仍 uncovered、恢复入口。课写完不是完成。
+
+## 无 slash-command 宿主
+
+`/goal` 是宿主适配示例，不是额外授权源。宿主没有该命令时，用户可在新执行会话明确请求“按此 Goal-Plan 执行”，同时提供计划路径；该会话成为外部执行器并遵守相同最小读取清单、owner、停止和验收合同。计划会话仍只编译并停止，不自动接管执行。无 team 时按原派单包串行执行；缺必需文件或工具只阻塞受影响分支，不伪造子代理调用。30–40 分钟、每单元 ≤15 节与每课最多10问仍是 Learning 领域合同，不传播为全局 Agent 限制。

package/template/workflows/learning/learning-g-goal/references/lead-orchestration.md

@@ -0,0 +1,52 @@
+# Lead 编排与派单（Learning `/goal`）
+
+本文件只在外部 `/goal` 执行 Goal-Plan，或 G-goal `plan` / `replan` 需要派只读库存员 / A 子代理时读取。不引入 SpecDev 的 Ticket / worktree / Evidence 协议。并发单位是「一个 Lesson 文件」或「一份 probe 文件」。
+
+抄 SpecDev `P-goal-plan` 的 lead-directed：主会话是唯一 Lead。Learning 不把 Lead 写进 Ticket；Lead 是当前 `/goal`（或 plan）主会话。
+
+## 角色与写集
+
+| 角色 | 何时出现 | 可以写 | 禁止写 | 必须读取 |
+| --- | --- | --- | --- | --- |
+| Lead（`/goal` 主会话，或 plan 主会话） | 始终 | `goal-plan` / `chain` / `matrix` / `progress` / `verify` / `lessons/INDEX` / `learning-log` / `.status.json` | 不得代替 L 写讲义正文，不得代替 miner 编造探针 | 已打开的 `workspace.json`、Goal-Plan §0/§5/§7/§8、`<Path>{roots.workflows}/learning/learning-g-goal/references/stop-rules.md</Path>`、本文件、`<Path>{roots.workflows}/learning/learning-g-goal/references/mine-unit.md</Path>`、`<Path>{roots.workflows}/learning/learning-g-goal/references/split-rules.md</Path>` |
+| 库存员（只读） | plan 可选 | 无 | 任何状态与知识文件 | 目标仓库源码，产出 C4 与函数分组给 Lead |
+| A 子代理 | plan 且尚无 `course.md` | `course.md`、background、baseline、sources、Change INDEX | `goal/`、`lessons/`、`probes/` | `A-assess-and-plan` 合同 |
+| L 子代理 | `/goal` 阶段 T，每课一个 | 仅被分配的 `lessons/L-<NNN>-<slug>.md` | 其他 L 文件、INDEX、`goal/`、`inquiry/` | `L-lesson.md` + teaching-policy + 该课 OBJ 与矩阵行 |
+| Miner 子代理 | `/goal` 阶段 M，每课一个 | 仅 `GP-<lesson>-b01.md` 与（若仍有预算）`b02.md` | `lessons/`、chain、matrix、`inquiry/`、其他课的 probe | 下面这条 skill 路径 + questioning-policy + 该课 Lesson + 源码锚点 + 该课声称覆盖的矩阵行 |
+
+Miner 必须加载的 skill 路径（不得另造配方）：
+
+```text
+{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md
+```
+
+## 派单包最低字段
+
+每次派单必须包含：`lesson_id` 或 change 范围、只读路径、唯一可写路径、允许动作、停止条件、返回格式。Miner 包还必须包含该课声称覆盖的矩阵行，以及上述 skill 合同路径。`audience` 固定为 `mine`。
+
+L 返回至少：`lesson_id`、写入路径、是否满足 L 合同章节、声称覆盖的格子。Miner 返回至少：`lesson_id`、`probe_id`、`question_budget_used`、缺口表、Q5/Q10 建议（`mine-more` | `defer` | `re-dispatch-L` | `split-lesson`）、可选 `split-proposal`。Miner 只填表，不选择处置。
+
+## 并发边界
+
+- `learning_agent_limit` 默认 4，硬顶为 `min(本单元课数, 15, 宿主能力)`。Lead 参与实现时计入。
+- 只有写集不相交才允许并行。两个 L 子代理不得写同一文件。两个 miner 不得写同一 GP 文件。
+- 跨 mine unit 不得同时写课或同时挖掘。
+- 矩阵、chain、progress、verify、`lessons/INDEX` 只有 Lead 可写。
+- 矩阵冲突只暂停受影响格子；其他课的 T/M 继续。不得抢锁、清空或覆盖他人写集。
+
+## 无宿主 team 时的顺序回退
+
+宿主没有 任务执行者 / agent team：Lead 按相同派单包顺序执行，合同不变。禁止因为不能并行就退回 `L → mine → L → mine` 交错。阶段 T 结束之前禁止任何 miner 启动。
+
+## 计划会话
+
+G-goal `plan` / `replan` 允许 Lead 派只读库存员，以及在没有 `course.md` 时派 A 子代理。Lead 自己写 `goal/*` 骨架，并按 mine-unit 规则切单元。计划会话仍然禁止写 `lessons/` 与 `goal/probes/`。
+
+## HARD NO
+
+- 不在阶段 T 完成前启动 miner
+- 不交错 L 与 mine
+- miner 不得写 `lessons/` 或 matrix
+- miner 不得选择处置
+- 同一 mine unit 不得超过 15 节
+- 宿主没有 team 时，不得借机退回旧交错循环

package/template/workflows/learning/learning-g-goal/references/orchestration-protocol.md

@@ -0,0 +1,26 @@
+# G-goal 编排协议
+
+G-goal 只在 `plan` / `replan` 中编排上游地图。授课与挖掘由外部 `/goal` 按 Goal-Plan 派单。`/goal` 采用 lead-directed：Lead 扇出、写集隔离、mine unit ≤15。细节读 `<Path>{roots.workflows}/learning/learning-g-goal/references/lead-orchestration.md</Path>` 与 `<Path>{roots.workflows}/learning/learning-g-goal/references/mine-unit.md</Path>`。
+
+## 计划会话允许跟随的合同
+
+- `I-init-setup`：没有状态时写空骨架
+- `A-assess-and-plan`：写出或核对 `course.md`、background、baseline、sources、Change INDEX
+- 可选只读库存员：产出 C4 与函数分组，不写状态
+
+不得跟随：`L-lesson`、`Q-question`、`H-homework`、`R-review`、`C-consolidate`、`A-archive`。不得写 `lessons/` 或 `goal/probes/`。
+
+## `/goal` 会话允许跟随的合同
+
+- `L-lesson`：写 `lessons/L-*.md`（阶段 T，每课一个 writer）
+- `socratic-questioning` 且 `audience=mine`：写 `goal/probes/GP-*.md`（阶段 M，每课一个 miner）
+
+不得跟随：`Q-question` 的 `inquiry/` Response 协议、H/R/C/A-archive。
+
+## 所有权
+
+派单不是改写所有权。A 仍拥有 course 地图，L 仍拥有 lessons，G 拥有 `goal/`，Q 拥有 `inquiry/`。矩阵、chain、progress、verify、`lessons/INDEX` 只有 Lead 可写。
+
+## 并发
+
+Lead 扇出 + 写集隔离。只有写集不相交才允许并行。同一 mine unit ≤15 节。Wave 不是并发授权，也不是挖掘门。禁止「同一时间只推进一个 chain 节点」的旧交错循环；禁止因为宿主没有 team 就退回 `L → mine → L → mine`。

package/template/workflows/learning/learning-g-goal/references/planning-modes.md

@@ -0,0 +1,19 @@
+# G-goal 规划模式
+
+本文件只在激活 G-goal 后按模式读取。
+
+## plan（默认）
+
+写出完整 Goal-Plan、Chain、覆盖矩阵和进度骨架，并可跟随 A 合同写 `course.md` / background / baseline / sources。按库存切出 mine unit 列表（每个 ≤15 节，小项目允许远小于 15）。不写 `lessons/`，不写 `goal/probes/`，不提问学习者，不预写探针题目或深化讲义。`ready_for_execution: false`。计划正文不授权执行。
+
+## replan
+
+源码、范围或用户目标变化时重编译。旧 `goal-plan.md` 移入 `goal/revisions/REV-<NNN>.md` 只读。已写成且仍覆盖有效格子的 Lesson 不删除；失效格子改 `deferred` 或重新入链。mine unit 按新库存重切，仍硬顶 15。
+
+## run / resume
+
+不由本 Work 在激活会话内执行。执行器是用户的外部 `/goal`，合同见 `<Path>{roots.workflows}/learning/learning-g-goal/references/external-goal-runner.md</Path>` 与当前 `goal-plan.md` §5 / §8。运行形状是四段：P 已由计划会话完成；`/goal` 对每个 mine unit 走 T（写完全部课）→ M（按课提问）→ D（Lead 深化或拆课），再进入下一 unit。按项目切 unit，硬顶 15。
+
+## verify
+
+对照矩阵与 `verify.md` 验收。课写完不是完成。可由 `/goal` 在停止规则触发后执行；以后再激活 G-goal 时也可以只读验收，仍不得补写 Lesson 或 probe，除非用户明确改回 `replan` 或把计划交给 `/goal`。

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-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/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-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>`

package/template/workflows/learning/manifest.json

@@ -1 +1,103 @@
-{"schema_version":1,"id":"learning","version":"1.0.0","persistent_knowledge":["<Path>{roots.state}/learning/context/INDEX.md</Path>","<Path>{roots.state}/learning/context/REVIEW.md</Path>"],"stages":[{"id":"intake","after":[],"inputs":["goal"],"outputs":["course"],"risk":"read-only","context_budget":12000},{"id":"teach","after":["intake"],"inputs":["course"],"outputs":["lesson"],"risk":"read-only","context_budget":18000},{"id":"practice","after":["teach"],"inputs":["lesson"],"outputs":["homework"],"risk":"read-only","context_budget":12000},{"id":"review","after":["practice"],"inputs":["homework"],"outputs":["mastery"],"risk":"read-only","context_budget":12000},{"id":"consolidate","after":["review"],"inputs":["lesson","mastery"],"outputs":["knowledge"],"risk":"local-reversible","context_budget":14000}]}
+{
+  "schema_version": 2,
+  "id": "learning",
+  "version": "1.0.0",
+  "persistent_knowledge": [
+    "<Path>{roots.state}/learning/context/INDEX.md</Path>",
+    "<Path>{roots.state}/learning/context/REVIEW.md</Path>"
+  ],
+  "stages": [
+    {
+      "id": "intake",
+      "after": [],
+      "inputs": [
+        "goal"
+      ],
+      "outputs": [
+        "course"
+      ],
+      "risk": "read-only",
+      "context_budget": 12000
+    },
+    {
+      "id": "teach",
+      "after": [
+        "intake"
+      ],
+      "inputs": [
+        "course"
+      ],
+      "outputs": [
+        "lesson"
+      ],
+      "risk": "read-only",
+      "context_budget": 18000
+    },
+    {
+      "id": "practice",
+      "after": [
+        "teach"
+      ],
+      "inputs": [
+        "lesson"
+      ],
+      "outputs": [
+        "homework"
+      ],
+      "risk": "read-only",
+      "context_budget": 12000
+    },
+    {
+      "id": "review",
+      "after": [
+        "practice"
+      ],
+      "inputs": [
+        "homework"
+      ],
+      "outputs": [
+        "mastery"
+      ],
+      "risk": "read-only",
+      "context_budget": 12000
+    },
+    {
+      "id": "consolidate",
+      "after": [
+        "review"
+      ],
+      "inputs": [
+        "lesson",
+        "mastery"
+      ],
+      "outputs": [
+        "knowledge"
+      ],
+      "risk": "local-reversible",
+      "context_budget": 14000
+    }
+  ],
+  "entry": "SKILL.md",
+  "works": [
+    "learning-a-archive/SKILL.md",
+    "learning-a-assess-and-plan/SKILL.md",
+    "learning-c-consolidate/SKILL.md",
+    "learning-g-goal/SKILL.md",
+    "learning-h-homework/SKILL.md",
+    "learning-i-init-setup/SKILL.md",
+    "learning-l-lesson/SKILL.md",
+    "learning-q-question/SKILL.md",
+    "learning-r-review/SKILL.md"
+  ],
+  "work_stages": {
+    "learning-a-archive/SKILL.md": [],
+    "learning-a-assess-and-plan/SKILL.md": [],
+    "learning-c-consolidate/SKILL.md": [],
+    "learning-g-goal/SKILL.md": [],
+    "learning-h-homework/SKILL.md": [],
+    "learning-i-init-setup/SKILL.md": [],
+    "learning-l-lesson/SKILL.md": [],
+    "learning-q-question/SKILL.md": [],
+    "learning-r-review/SKILL.md": []
+  }
+}