@namewta/speculo 0.1.4 → 0.1.5

package/README.md

@@ -60,7 +60,7 @@ speculo update my-project
 - `workflows/dev/03-tdd/03-tdd.md`：TDD 实现
 - `workflows/dev/I-to-issues/I-to-issues.md`：`dev/I` 垂直切片分解
 - `workflows/dev/H-diagnose/H-diagnose.md`：`dev/H` hotfix / diagnose
-- `workflows/dev/R-review/R-review.md`：`dev/R` 双维度 diff 审查
+- `workflows/dev/R-review/R-review.md`：`dev/R` Spec / Engineering / Standards 三维度 diff 审查
 - `workflows/dev/D-docs-sync/D-docs-sync.md`：`dev/D` git diff 驱动文档同步
 - `workflows/doc/00-INDEX.md`：文档写作 workflow 导航
 - `commands/status.md`：聚合当前状态
@@ -78,6 +78,13 @@ pnpm test
 
 运行环境锁定为 Node `22.22.3`、pnpm `11.1.3`。
 
+## 致谢 / Acknowledgements
+
+Speculo 的设计受益于以下项目的理念与实践：
+
+- **[Matt Pocock / skills](https://github.com/mattpocock/skills)** — 技能封装与渐进披露模式的重要参考
+- **[NAMEWTA / specforge](https://github.com/NAMEWTA/specforge)** — 同属 SDD 工具链的兄弟项目，规格生成与验证的互补实践
+
 ## 文档导航
 
 - 使用者必读：[adopting.md](docs/adopting.md) · [quick-reference.md](docs/quick-reference.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/speculo/workflows/dev/03-tdd/03-tdd.md

@@ -58,15 +58,15 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - 完成准则：
   - 已运行相关测试或明确记录无法运行原因
   - 无调试残留和推测性功能
-  - 已把 roadmap 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 roadmap 则跳过，见「roadmap 阶段状态（XML 契约）」）
+  - 已把 slices 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 slices 则跳过，见「phase 阶段状态（XML 契约）」）
   - `verification.md` 无残留 `[TODO:]`
 
 ## TDD 产物目录与阶段标识
 
-- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / roadmap 等产物分离，便于多阶段并行与回溯。
+- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
 - `<phase-id>` 标识：
-  - change 来自**多阶段 roadmap** 时，用 roadmap 阶段标识（与 roadmap `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
-  - change 为**单阶段**（无 roadmap 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
+  - change 来自**多阶段 slices** 时，用 slices 阶段标识（与 slices `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
+  - change 为**单阶段**（无 slices 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
 - 每个阶段独立一套 `tdd-plan.md` / `implementation-log.md` / `verification.md`，互不覆盖；模板顶部「阶段标识」段记录该 `<phase-id>`。
 - 目录形如：
 
@@ -82,9 +82,9 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
     └── verification.md
 ```
 
-## roadmap 阶段状态（XML 契约）
+## phase 阶段状态（XML 契约）
 
-多阶段 roadmap（`.speculo/dev/<change>/roadmap.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
+多阶段 change（`.speculo/dev/<change>/slices.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
 
 ```xml
 <phase id="phase0-node-base" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
@@ -92,11 +92,11 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 - `id`：阶段稳定标识，与 TDD 产物目录 `tdd/<phase-id>/` 同名。
 - `status` 枚举与责任方：
-  - `未开始` —— 创建 roadmap 文档时由作者初始化（所有阶段默认 `未开始`）。
+  - `未开始` —— 创建 slices 文档时由作者初始化（所有阶段默认 `未开始`）。
   - `已实现` —— 本工作流（`dev/03`）该阶段 Finish 验证通过后置入。
   - `已验证` —— `dev/04`（`../04-finalize/04-finalize.md`）完成前验证通过后置入。
 - 本工作流只负责 `未开始 → 已实现` 这一跳；`dev/04` 负责 `已实现 → 已验证`。状态只前进不回退，除非该阶段被显式重做。
-- change 无 roadmap（单阶段直接任务）时本契约不适用，跳过状态翻转。
+- change 无 slices（单阶段直接任务）时本契约不适用，跳过状态翻转。
 
 ## 依赖
 
@@ -109,7 +109,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 - `dev_entry` (string) — 固定为 `dev/03`
 - `embedded_guides` (array) — 包含 `tdd`
-- `tdd_phase_id` (string) — 当前 TDD 阶段标识，与产物目录 `tdd/<phase-id>/` 及 roadmap `<phase>` 的 `id` 一致
+- `tdd_phase_id` (string) — 当前 TDD 阶段标识，与产物目录 `tdd/<phase-id>/` 及 slices `<phase>` 的 `id` 一致
 - `slice_source` (prd | issues | diagnosis | user-request) — 切片来源
 - `red_green_refactor_cycles` (array) — 每轮 TDD 循环摘要
 - `verification_commands` (array) — 已运行或应运行的验证命令
@@ -121,5 +121,5 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 每完成一个切片，追加 `red_green_refactor_cycles`（多阶段时写入 `tdd_runs[<phase-id>]`）。
-- Finish 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 roadmap 则跳过）。
+- Finish 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 slices 则跳过）。
 - 全部用户要求的实现边界完成并验证后，可把 `change_status` 置为 `completed`，或移交 review/handoff command。

package/speculo/workflows/dev/03-tdd/tdd-finish.md

@@ -15,7 +15,7 @@
 1. 运行与变更相关的测试、类型检查、lint 或构建命令。
 2. 记录无法运行的命令和阻塞原因。
 3. 搜索临时调试标记、一次性脚本和推测性实现。
-4. 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「roadmap 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 roadmap 则跳过）。
+4. 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「phase 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 slices 则跳过）。
 5. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
 
 ## 边界
@@ -25,6 +25,6 @@
 
 ## 完成准则
 
-- 多阶段 roadmap：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 roadmap 则不适用）
+- 多阶段 slices：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 slices 则不适用）
 - `verification.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

package/speculo/workflows/dev/03-tdd/tdd-plan.md

@@ -26,6 +26,6 @@
 
 ## 完成准则
 
-- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 roadmap 须与 `<phase>` 的 `id` 一致）
+- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 slices 须与 `<phase>` 的 `id` 一致）
 - `tdd-plan.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `planned`

package/speculo/workflows/dev/04-finalize/04-finalize.md

@@ -126,7 +126,7 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 完成验证后写入 `verification_commands`、`requirements_checklist`、`verification_status`。
-- 多阶段 roadmap：完成前验证为 `verified` 后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「roadmap 阶段状态（XML 契约）」的最后一跳；无 roadmap 则跳过）。
+- 多阶段 slices：完成前验证为 `verified` 后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「phase 阶段状态（XML 契约）」的最后一跳；无 slices 则跳过）。
 - 验证为 `blocked` 时停在本工作流，回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复，不归档。
 - 验证为 `verified` 且用户确认后：
   - **worktree 模式**：先执行 Phase 2，自动把 change 分支合并回 `base_branch` 并清理工作树与隔离分支（`worktree_status: merged` → `removed`，冲突即停），再在 base 分支上归档；非 worktree 模式跳过 Phase 2。

package/speculo/workflows/dev/04-finalize/completion-gate.md

@@ -37,5 +37,5 @@
 - 需求清单逐项核对完成，含来源引用
 - 调试残留已清理或明确说明
 - `completion-verification.md` 无残留 `[TODO:]`
-- 多阶段 roadmap：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 roadmap 则不适用）
+- 多阶段 slices：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 slices 则不适用）
 - `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`

package/speculo/workflows/dev/I-to-issues/issues-slices.md

@@ -1,31 +1,108 @@
 # Slice Issues Phase
 
+> 本阶段将 PRD、计划或诊断结论拆为**可独立验证的垂直切片**（tracing bullet），产出兼具路线图信息密度的 `slices.md`。
+> `slices.md` 融合了原 roadmap.md 的阶段规划能力——按 scope / architecture / phases / cross-cutting / dependency 五段结构组织，
+> 同时保留 HITL/AFK 标记、用户确认与 issue 发布流程。
+
 ## 输入
 
 - `prd.md`、`decision-log.md`、`diagnosis.md`、现有 issue 或用户计划
 - 可选 issue tracker 配置和标签词汇表
 - `I-to-issues.md` 中的内置切片指引
+- 同级 change 目录下已有的 `context-map.md`、`decision-log.md`（若存在，用于继承领域术语与 ADR 引用）
 
 ## 产物
 
 - `.speculo/dev/<change>/slices.md`，由 `../_templates/issues-slices-template.md` 填写
 
+## `slices.md` 格式规范（五段结构）
+
+`issues-slices-template.md` 提供模板骨架；AI 在填写时**必须**按以下五段结构展开，使 `slices.md` 融合 roadmap.md 的信息密度：
+
+### 0. 一句话战略（strategic anchor）
+
+单句概括本 change 的「做什么 + 为什么 + 怎么做到（以现有系统为基底 / 新建 / 复用）」。从 PRD 或用户意图提炼，为后续所有切片提供决策锚点。
+
+### 1. 范围边界（IN / REUSE / OUT）
+
+三列表格，逐条列出：
+- **IN** —— 本次必造的新能力（每项可对应后续一个或多个切片）
+- **REUSE** —— 复用现有系统的能力（不改动，只收编进新地基）
+- **OUT** —— 本期不做、留给后续迭代的内容
+
+表格来源优先从 PRD 或用户指令提取；若来源未明确，用 `[待确认]` 标记并提请用户补充。
+
+### 2. 架构上下文（可选，有则填）
+
+若 change 涉及多模块或改动既有架构，本节记录：
+- 涉及的 `core/` / `src/` / `src-tauri/` 模块及其职责分工
+- 新增模块的定位（一句话职责 + 落点目录）
+- 不可逾越约束（来自 `AGENTS.md` 或 PRD 的硬性规则）
+
+本节不是必需的；单文件修复或热点 patch 可省略。
+
+### 3. 切片（phases）
+
+每个切片是**一个从数据到 UI 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
+
+```markdown
+### 切片 N · 切片名称
+<phase id="<phase-id>" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+
+- **类型：** `AFK` | `HITL`
+- **阻塞于：** 切片 M（或「无」）
+- **覆盖：** PRD 章节 / US 编号 / 用户故事简述
+- **交付物：** 该切片产出的具体文件/模块/功能清单
+- **复用：** 复用哪些现有能力（模块/文件/命令）
+- **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成
+- **对齐：** PRD FR-xxx 或 issue 引用
+- **ADR 引用：** （可选）关联的工程层 ADR 编号
+```
+
+- `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
+- `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
+
+### 4. 横切关注点（贯穿所有切片）
+
+列出跨切片一致的规则与约束，如：
+- 磁盘契约先改 zod + fixtures 再改解析
+- 删缓存可重建铁律
+- 范围隔离规则（不 import 旧 AI 子系统等）
+- 命名消歧规则
+
+### 5. 依赖顺序速查
+
+ASCII 依赖链，展示切片先后顺序：
+
+```
+P0  切片0  名称    ← 不可回退,最先
+P1  切片1  名称
+P2  切片2  名称    依赖 P0+P1
+...
+```
+
+> **判据：** 每个切片的「验收切片」全部通过即该切片完成；所有切片完成 = change 可进入 `dev/04` 收尾。
+
 ## 填写引导
 
-1. 遵循 `I-to-issues.md` 的内置切片指引。
-2. 先本地起草切片，按垂直切片原则覆盖端到端行为。
-3. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记和是否需要发布。
-4. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
-5. 每个切片展示标题、类型、被哪些切片阻塞、覆盖的用户故事或来源。
-6. 迭代直到用户批准分解；未批准前不发布外部 issue。
+1. 遵循 `I-to-issues.md` 的内置切片指引和本文件的五段格式。
+2. **采集来源**：从 PRD / decision-log / diagnosis / 用户指令中提取 IN/REUSE/OUT 三列、架构上下文和 ADR 引用；不确定的标记 `[待确认]`。
+3. **切分垂直切片**：优先窄而完整、优先 AFK；每个切片必须有用户可独立验证的「验收切片」。
+4. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
+5. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
+6. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
+7. 迭代直到用户批准分解；未批准前不发布外部 issue。
 
 ## 边界
 
 - 不关闭或修改父级 issue。
 - 不默认发布到外部 tracker。
 - 不写实现代码。
+- 不编造来源；PRD/ADR/issue 引用必须真实存在。
 
 ## 完成准则
 
 - `slices.md` 无残留 `[TODO:]`
+- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、验收切片
+- IN/REUSE/OUT 表格完整（无法确定时标 `[待确认]` 并已获用户补充）
 - `.status.json` 已记录 `slice_count`、`hitl_slice_count` 和 `issue_tracker_mode`

package/speculo/workflows/dev/_templates/issues-slices-template.md

@@ -3,17 +3,64 @@
 
 # Vertical Slices
 
-## 来源
-[TODO: 记录切片来源，如 PRD、计划、诊断结论、issue 或用户请求。]
+> 本文件融合了 roadmap 的 scope/architecture/phases/cross-cutting/dependency 五段结构与垂直切片标记。
+> 每个切片有 `<phase id="...">` 标识，供 TDD 工作流直接引用。
 
-## 切片列表
-[TODO: 用编号列表列出每个切片的标题、HITL/AFK 类型、依赖和覆盖的用户故事。]
+## 0. 一句话战略
+[TODO: 单句概括：做什么 + 为什么 + 怎么做到（新建/复用/以现有系统为基底）。]
 
-## 依赖顺序
-[TODO: 按可执行顺序列出切片，并说明阻塞关系。]
+## 1. 范围边界（IN / REUSE / OUT）
+[TODO: 三列表格。]
+| | 内容 |
+|---|---|
+| **IN 必造** | [TODO: 本次必造的新能力] |
+| **REUSE 复用现有** | [TODO: 复用不改动的现有能力] |
+| **OUT 本期不做** | [TODO: 留给后续迭代的内容] |
+
+## 2. 架构上下文
+[TODO: 涉及的模块与职责分工、新增模块定位、不可逾越约束。单文件修复可省略本节。]
+
+## 3. 切片
+
+### 切片 1 · [切片名称]
+<phase id="[phase-id]" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+
+- **类型：** AFK | HITL
+- **阻塞于：** 无
+- **覆盖：** [TODO: PRD 章节 / US 编号 / 用户故事]
+- **交付物：** [TODO: 具体文件/模块/功能]
+- **复用：** [TODO: 复用哪些现有能力]
+- **验收切片：** [TODO: 可独立执行的验证命令或步骤]
+- **对齐：** [TODO: PRD FR-xxx 或 issue 引用]
+- **ADR 引用：** [TODO: 关联的 ADR 编号，可选]
+
+### 切片 2 · [切片名称]
+<phase id="[phase-id]" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+
+- **类型：** AFK | HITL
+- **阻塞于：** 切片 1
+- **覆盖：** [TODO]
+- **交付物：** [TODO]
+- **复用：** [TODO]
+- **验收切片：** [TODO]
+- **对齐：** [TODO]
+- **ADR 引用：** [TODO]
+
+[TODO: 按需增加更多切片，每个有独立的 phase id]
+
+## 4. 横切关注点
+[TODO: 跨切片一致的规则与约束。]
+
+## 5. 依赖顺序速查
+```
+[TODO: ASCII 依赖链，如:
+P0  phase0-xxx  切片名称  ← 不可回退,最先
+P1  phase1-xxx  切片名称  依赖 P0
+]
+```
 
 ## 用户确认
-[TODO: 记录用户对粒度、依赖、HITL/AFK 标记和发布策略的确认。]
+[TODO: 记录用户对粒度、依赖、HITL/AFK 标记、phase id 和发布策略的确认。]
 
 ## 发布记录
 [TODO: 若发布到外部 issue tracker，记录 issue 引用；否则写明 local-only。]

package/speculo/workflows/dev/_templates/tdd-plan-template.md

@@ -4,7 +4,7 @@
 # TDD Plan
 
 ## 阶段标识
-[TODO: 本阶段 `<phase-id>`。多阶段 roadmap 须与 roadmap `<phase>` 的 `id` 一致（如 `phase0-node-base`）；单阶段 change 用描述性切片 slug。产物落 `tdd/<phase-id>/`。]
+[TODO: 本阶段 `<phase-id>`。多阶段 slices 须与 slices `<phase>` 的 `id` 一致（如 `phase0-node-base`）；单阶段 change 用描述性切片 slug。产物落 `tdd/<phase-id>/`。]
 
 ## 切片来源
 [TODO: 记录来自 PRD、slices、diagnosis 还是用户直接请求。]

package/speculo/workflows/doc/00-INDEX.md

@@ -14,6 +14,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 
 | 别名 | 入口 | 用途 |
 |------|------|------|
+| `doc/T` | `T-teach/T-teach.md` | 设计交互式课程：使命→资源→课程→参考→记录 |
 | `doc/F` | `F-writing-fragments/F-writing-fragments.md` | 追问式访谈，沉淀异质 fragment 素材 |
 | `doc/B` | `B-writing-beats/B-writing-beats.md` | 逐个 beat 推进文章旅程 |
 | `doc/S` | `S-writing-shape/S-writing-shape.md` | 读取素材堆并对话式塑造成文章 |
@@ -29,6 +30,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 
 ## 执行模式
 
+- `teach`：想学某个主题，需要设计交互式课程体验，进入 `doc/T`。
 - `fragments`：从主题和对话中采集素材，进入 `doc/F`。
 - `beats`：已有素材，想逐个转向推进叙事，进入 `doc/B`。
 - `shape`：已有素材堆或粗稿，想塑造成可发布文章，进入 `doc/S`。

package/speculo/workflows/doc/T-teach/T-teach.md

@@ -0,0 +1,147 @@
+---
+id: doc/teach
+category: doc
+name: Teaching Design
+description: 设计交互式学习体验：确立使命、策展资源、构建术语、制作课程、记录洞察
+keywords: [teach, lesson, learning, glossary, 教学, 课程, 术语, 学习]
+---
+
+# Teaching Design 工作流执行指引
+
+本工作流用于在项目内围绕一个学习主题，设计并交付交互式教学体验。它是 `doc/T` 入口，覆盖从使命确立到课程产出、参考文档和洞察记录的完整链路。
+
+## 内置指引
+
+### 核心理念
+
+深度学习需要三样东西：
+
+- **Knowledge（知识）** — 从高质量、高信任度资源获取
+- **Skills（技能）** — 通过你设计的高度相关交互式课程获得
+- **Wisdom（智慧）** — 来自与其他学习者和实践者的互动
+
+获取知识时，难度是敌人——它会吃掉理解所需的工作记忆。练习技能时，难度是工具——有努力的提取才能建立长期留存。
+
+### 留存设计原则
+
+- **Retrieval practice**：让用户从记忆中回忆，而非重新阅读
+- **Spacing**：把练习分散到多节课，不要集中轰炸
+- **Interleaving**：在技能练习中混合不同但相关的主题
+
+每节课应该短小精悍，在很短时间内可完成。学习者工作记忆很有限，必须控制在容量内。但每节课应该给用户一个具体的小胜利。
+
+### 最近发展区
+
+每节课用户都应该感觉被挑战得「刚好够」。判断最近发展区的方法：
+
+1. 读取 `learning-records/`，了解用户已知什么
+2. 基于使命判断下一个该教什么
+3. 教能放进最近发展区的最相关内容
+
+### Lesson 铁律
+
+一节 lesson 是自包含的单个 HTML 文件，保存为 `.speculo/doc/<change>/lessons/<编号>.html`。它必须：
+
+- **漂亮** — 干净、可读的排版和布局，用户以后会回来复习
+- **短** — 在几分钟内可完成
+- **给一个胜利** — 每节课一个具体可感知的收获
+- **直接关联使命** — 每节课都追溯回 MISSION.md
+- **链向其他资源** — 通过 HTML 锚点链向其他课程和参考文档
+- **推荐一手资料** — 每节课推荐一个最高质量、最高信任度的外部资源
+- **提示提问** — 每节课包含提醒用户向 AI 教师追问
+
+### 课程结构模板
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<title>课程标题</title>
+<style>
+  body { max-width: 680px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui; line-height: 1.7; color: #1a1a1a; }
+  h1 { font-size: 1.6rem; margin-top: 2.5rem; }
+  blockquote { border-left: 3px solid #ddd; margin-left: 0; padding-left: 1rem; color: #555; }
+  .cite { font-size: 0.85rem; color: #888; margin-top: 2rem; border-top: 1px solid #eee; padding-top: 0.5rem; }
+  .reminder { background: #f5f5f5; padding: 0.8rem 1rem; border-radius: 6px; margin-top: 2rem; font-size: 0.9rem; }
+</style>
+</head>
+<body>
+<!-- 课程内容 -->
+<div class="cite">📖 推荐一手资料：<a href="...">资源标题</a></div>
+<div class="reminder">💡 有疑问？直接问我——我是你的 AI 教师。</div>
+</body>
+</html>
+```
+
+## 阶段
+
+> **产物目录：** 本工作流所有产物写入 `.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。
+
+### 1. Mission Setup — 确立学习使命
+- 规范：`teach-mission.md`
+- 模板：`../_templates/teach-mission-template.md`
+- 产物：`mission.md`
+- 完成准则：
+  - 已追问出具体、可观测的成功标准（非「想了解 X」而是「能做 Y」）
+  - Why / Success / Constraints / Out of scope 四段均已填写
+  - `mission.md` 无残留 `[TODO:]`
+
+### 2. Resources Curation — 策展可信资源
+- 规范：`teach-resources.md`
+- 模板：`../_templates/teach-resources-template.md`
+- 产物：`resources.md`
+- 完成准则：
+  - 已搜集高信任度知识源（优先一手资料、公认专家、同行评审）
+  - 每条资源有注解：覆盖什么、何时取用
+  - 已找到至少一个可推荐社区（除非用户选择不加入社区）
+  - `resources.md` 无残留 `[TODO:]`
+
+### 3. Lesson Design — 设计一节交互式课程（主循环）
+- 规范：`teach-lesson.md`
+- 模板：无（HTML 课程见内置指引的课程结构模板）
+- 产物：`lessons/<编号>.html`
+- 完成准则：
+  - 课程短小（几分钟内可完成）、有一个具体胜利、直接关联使命
+  - 课程已链向相关参考文档和其他课程
+  - 课程包含一手资料推荐和 AI 追问提示
+  - 编号从已有最高编号 +1
+
+### 4. Lesson Wrap — 课程收尾
+- 规范：`teach-lesson-wrap.md`
+- 模板：`../_templates/teach-glossary-template.md`、`../_templates/teach-learning-record-template.md`
+- 产物：`reference/<编号>.html`、`GLOSSARY.md`（持续更新）、`learning-records/<编号>.md`（可选）
+- 完成准则：
+  - 已为该课程创建压缩参考文档（cheat sheet / 速查）
+  - 用户在本课中真正理解的术语已收录进 GLOSSARY.md
+  - 若产生非显而易见的洞察，已写 learning record
+  - 已更新 `NOTES.md`（若用户表达了教学偏好）
+
+## 依赖
+
+- 硬依赖：Phase 1 → Phase 2，使命未确立前不得策展资源
+- 软依赖：Phase 2 → Phase 3，建议先有资源再设计课程
+- Phase 3 ↔ Phase 4 为紧密循环：每节课程完成后立即收尾
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `doc_entry` (string) — 固定为 `doc/T`
+- `mission_status` (drafting | confirmed) — 使命确认状态
+- `resource_count` (number) — 已策展资源数量
+- `lesson_count` (number) — 已创建课程数量
+- `reference_count` (number) — 已创建参考文档数量
+- `learning_record_count` (number) — 已写学习记录数量
+- `glossary_term_count` (number) — 术语表条目数
+- `current_loop` (mission | resources | lesson | wrap) — 当前循环位置
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- Phase 1 完成且用户确认使命后，`mission_status` 置为 `confirmed`。
+- Phase 3-4 为循环：每次完成一节课程和收尾后，更新 `lesson_count`、`reference_count`、`glossary_term_count`。
+- 每次捕捉到学习洞察时追加 `learning_record_count`。
+- 用户声明学习目标全部达成后，可把 `change_status` 置为 `completed`。
+- 如有可沉淀教学经验，在用户允许时追加到 `.speculo/.config/LESSONS.md`。
+- NOTES.md 作为教学偏好暂存区，AI 在后续课程设计中应参考其中记录。

package/speculo/workflows/doc/T-teach/teach-lesson-wrap.md

@@ -0,0 +1,63 @@
+# Lesson Wrap Phase
+
+本阶段在每节课程完成后立即执行，产出该课的压缩参考文档、更新术语表，并在产生非显而易见的洞察时写学习记录。
+
+## 输入
+
+- `.speculo/doc/<change>/lessons/<编号>.html` — 刚完成的课程
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语表（若不存在则创建）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好
+
+## 产物
+
+- `.speculo/doc/<change>/reference/<编号>.html` — 本节课程的压缩参考文档
+- `.speculo/doc/<change>/GLOSSARY.md` — 更新后的术语表
+- `.speculo/doc/<change>/learning-records/<编号>.md` — 可选，仅当产生了非显而易见的洞察
+- `.speculo/doc/<change>/NOTES.md` — 可选，仅当用户表达了新的教学偏好
+
+## 填写引导
+
+### 创建参考文档
+
+1. 从刚完成的课程中提取最核心的内容——语法、算法、步骤、要点。
+2. 写成紧凑的 HTML 速查文档，设计上适合打印。干净排版，易扫读。
+3. 链接回原课程 HTML 和术语表中的相关条目。
+4. 参考文档是课程被复习时的入口——课程很少被重看，参考文档会。
+
+### 更新术语表
+
+1. 仅当用户在本课中**真正理解**了某个术语时才收录——术语表是压缩知识的记录，不是字典。
+2. 每条定义 1-2 句，说清术语**是什么**，不说它做什么或怎么做。
+3. 有多个同义词时选最佳者，其余标为「避免使用」。
+4. 术语表自身术语应互相引用——一旦一个术语入库，后续定义优先使用它。
+5. 用户理解加深时在原文上修订，不留过时条目。
+
+### 写学习记录（可选）
+
+仅当以下任一条件成立时写：
+
+1. 用户展示了非显而易见的真正理解
+2. 用户披露了先验知识（避免后续重新教）
+3. 一个误解被纠正（高价值：预测后续相关主题的绊脚石）
+4. 使命因学习而改变（更新 mission.md 并交叉引用）
+
+学习记录是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+
+### 更新 NOTES.md
+
+若用户在本课中表达了教学偏好（如「我更想要视频」「不要太多术语」「多给练习」），记录到 NOTES.md 供后续课程设计参考。
+
+## 边界
+
+- 不写入用户尚未真正理解的术语。
+- 学习记录不记「已覆盖了某内容」——覆盖不等于学会。
+- 不重复术语表中已有的内容到学习记录中。
+
+## 完成准则
+
+- 参考文档已创建在 `reference/<编号>.html`
+- 用户本课真正理解的术语已收录进 `GLOSSARY.md`（或确认无需新增）
+- 若产生符合条件的学习洞察，已写 learning record
+- 若用户表达了新偏好，已更新 `NOTES.md`
+- `.status.json` 已更新 `lesson_count`、`reference_count`、`glossary_term_count`、`learning_record_count`

package/speculo/workflows/doc/T-teach/teach-lesson.md

@@ -0,0 +1,53 @@
+# Lesson Design Phase（主循环）
+
+本阶段是教学设计的核心循环。每次执行只设计**一节**课程，完成后进入 Phase 4 收尾，再回到本阶段设计下一节。
+
+## 输入
+
+- `.speculo/doc/<change>/mission.md` — 教学使命
+- `.speculo/doc/<change>/resources.md` — 可信资源
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语（若存在）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好（若存在）
+- `.speculo/doc/<change>/lessons/` — 已有课程（判断最近发展区）
+
+## 产物
+
+- `.speculo/doc/<change>/lessons/<编号>.html`，按 `T-teach.md` 内置指引中的课程结构模板创建
+- 编号规则：扫描 `lessons/` 下已有最高编号 +1，起始 `0001`
+
+## 填写引导
+
+1. **判断最近发展区**：
+   - 读取已有 learning records 和 GLOSSARY.md，了解用户已知什么
+   - 基于使命中尚未覆盖的 Success 项，选择下一个该教的内容
+   - 教能放进最近发展区的最相关内容
+2. **知识先行，技能随后**：
+   - 课程前半段：从 resources.md 中的高信任度源提取知识，用最简洁的方式呈现
+   - 课程后半段：设计交互式练习或真实世界步骤，让用户实践
+   - 知识部分引用来源，每条声明有出处
+3. **设计反馈循环**：
+   - 如果是问答题，每个选项等长（避免通过格式暗示答案）
+   - 反馈尽可能即时、自动
+   - 练习的目标是建立 storage strength，不是 fluency
+4. **保持短小**：课程应在几分钟内完成。如果知识或练习过多，拆成多节。
+5. **关联使命**：课程开头一句话说明本节如何贡献于使命中的哪个 Success 项。
+6. **链向其他材料**：通过 HTML 锚点链向已有术语表、参考文档和相关课程。
+7. **每节课程末尾**：推荐一个一手资料（从 resources.md 中选取）+ 提示用户可追问 AI 教师。
+8. **创建后**：尝试自动打开 HTML 文件供用户查看。
+
+## 边界
+
+- 每次只设计一节课程，不批量预写后续课程。
+- 不编造知识——所有事实性声明必须来自 resources.md 中的资源。
+- 不假设用户记得上一节的内容——可以引用但关键概念要简要回顾。
+- 不在课程中加入超出使命范围的话题。
+
+## 完成准则
+
+- 课程 HTML 已创建在 `lessons/<编号>.html`
+- 课程短小（几分钟内可完成）
+- 课程包含知识部分（有引用来源）+ 技能练习部分（有反馈循环）
+- 课程关联使命中的具体 Success 项
+- 课程包含一手资料推荐和 AI 追问提示
+- `T-teach.md` 内置指引的课程铁律已全部满足

package/speculo/workflows/doc/T-teach/teach-mission.md

@@ -0,0 +1,33 @@
+# Mission Setup Phase
+
+## 输入
+
+- 用户声明的学习主题或模糊兴趣
+- 用户对「为什么想学这个」的任何初始表述
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+
+## 产物
+
+- `.speculo/doc/<change>/mission.md`，由 `../_templates/teach-mission-template.md` 填写
+
+## 填写引导
+
+1. 若用户未给出具体目标，追问「你学这个最终想做到什么？」，直到得到可观测的行为描述——不是「了解 X」而是「能做 Y」。
+2. 从用户的回答中提炼 Why（1-3 句）、Success（具体可观测事项）、Constraints（时间/预算/偏好）、Out of scope（明确不做的话题）。
+3. 追问时保持具体：避免抽象框架，逼向真实世界的成果。
+4. 用户说不清时，继续访谈；坏使命比没使命更糟，但模糊使命也要被推回。
+5. 使命确立后与用户逐条确认，确认后才进入 Phase 2。
+
+## 边界
+
+- 不在此阶段搜集学习资源或设计课程。
+- 不编造用户的动机或目标——一切来自用户原话。
+- 使命可以后续修订，但修订必须经用户确认并写 learning record 记录变更原因。
+
+## 完成准则
+
+- Why / Success / Constraints / Out of scope 四段均已填写
+- 每条 Success 是可观测的、可判断是否达成的
+- 用户已逐条确认使命内容
+- `mission.md` 无残留 `[TODO:]`
+- 已创建 `NOTES.md`（空文件，用于后续记录教学偏好）

package/speculo/workflows/doc/T-teach/teach-resources.md

@@ -0,0 +1,36 @@
+# Resources Curation Phase
+
+## 输入
+
+- `.speculo/doc/<change>/mission.md`（已确认的使命）
+- 用户的社区偏好（是否愿意加入线上/线下社区）
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+
+## 产物
+
+- `.speculo/doc/<change>/resources.md`，由 `../_templates/teach-resources-template.md` 填写
+
+## 填写引导
+
+1. **搜罗知识源**：针对使命中的每个 Success 项，搜寻高信任度资源。
+   - 优先：一手资料、公认专家著作、同行评审、强审核社区
+   - 避开：营销伪装成教育的内容、无引用的自媒体
+2. **注解每条资源**：用一句话写清覆盖什么、何时取用。裸链接三个月后无用。
+3. **分 Knowledge / Wisdom 两组**：
+   - Knowledge：书籍、文章、课程、论文——用于获取知识
+   - Wisdom：社区、论坛、线下课——用于获取智慧
+4. **标明缺口**：若某个 Success 项找不到好资源，在 `## Gaps` 段写明。
+5. **用户选择不加入社区时**，在 Wisdom 段记录此偏好，后续课程中不再推荐社区。
+
+## 边界
+
+- 不在此阶段设计课程。
+- 不因为资源少而编造或降级标准。
+- 不在 resources.md 中写课程计划或教学大纲。
+
+## 完成准则
+
+- 已针对使命中每个 Success 项搜集至少一条高信任度知识源（或在 Gaps 中标记缺失）
+- 每条资源有注解
+- 已找到至少一个可推荐社区（或记录用户拒绝社区）
+- `resources.md` 无残留 `[TODO:]`

package/speculo/workflows/doc/_templates/teach-glossary-template.md

@@ -0,0 +1,25 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `GLOSSARY.md`
+
+# [TODO: 学习主题] Glossary
+
+[TODO: 1-2 句描述本术语表覆盖的主题范围。]
+
+## Terms
+
+[TODO: 每个术语 1-2 句，说清它**是什么**，不说它做什么或怎么做。术语表自身术语互相引用。]
+
+**[TODO: 术语名]**：
+[TODO: 定义——术语是什么。]
+_Avoid_: [TODO: 列出应避免的同义词或不当用语]
+
+**[TODO: 术语名]**：
+[TODO: 定义。]
+_Avoid_: [TODO: 不当用语]
+
+## Rules
+- 仅在用户**真正理解**术语后才收录——术语表是压缩知识的记录，不是字典。
+- 有自己的观点：当多个词指向同一概念时，选最佳者，其余标为避免使用。
+- 定义内部使用术语表自身的术语——一旦入库，后续定义优先使用它。
+- 理解加深时在原文上修订，不留过时条目。
+- 若某术语在更广领域中用法模糊，注明本 workspace 内的约定用法。

package/speculo/workflows/doc/_templates/teach-learning-record-template.md

@@ -0,0 +1,37 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `learning-records/<编号>.md`
+
+学习记录使用顺序编号：`0001-<slug>.md`、`0002-<slug>.md`。首次写入时创建目录。
+
+每一条是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+
+## 模板
+
+```markdown
+# [TODO: 简短标题——学到了什么或建立了什么认知]
+
+[TODO: 1-3 句。学到了什么（或建立了什么先验知识），以及为什么这会影响后续课程。]
+```
+
+## 何时写
+
+仅在以下任一条件成立时写：
+
+1. **用户展示了非显而易见的真正理解** — 不是仅仅接触过，而是有证据表明能正确使用这个概念。这为后续教学设定了新底线。
+2. **用户披露了先验知识** — 「我已经知道 X」。记录下来避免后续重新教。同时记录声称的深度。
+3. **一个误解被纠正** — 用户之前相信了错误的东西，现在明白了为什么。高价值：预测后续相关主题的绊脚石。
+4. **使命因学习而改变** — 用户发现自己在意的和最初想的不同。交叉引用 [[mission.md]] 并更新它。
+
+### 不写的情况
+
+- 仅仅覆盖过的内容。覆盖 ≠ 学会。等证据。
+- 已被 GLOSSARY.md 精简收录的术语定义。不重复。
+- 逐节课的活动日志。学习记录不是流水账——是决策级的洞察。
+
+## 可选节
+
+仅在真正增值时加入：
+
+- **Status frontmatter**：`active | superseded by LR-NNNN` — 当早期理解被后续认知推翻时使用。
+- **Evidence**：用户如何展示理解（回答的问题、完成的练习、引用的先验经历）。
+- **Implications**：这对后续课程解锁或排除了什么。

package/speculo/workflows/doc/_templates/teach-mission-template.md

@@ -0,0 +1,18 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `mission.md`
+
+# Mission: [TODO: 学习主题]
+
+## Why
+[TODO: 1-3 句。用户追逐的具体真实世界目标。学会这个之后，他们的生活或工作中会发生什么改变？避免「想了解 X」这类抽象表述——逼向底层成果。]
+
+## Success looks like
+- [TODO: 一个具体的、可观测的用户将能做到的事项]
+- [TODO: 另一个具体事项]
+- [TODO: …]
+
+## Constraints
+- [TODO: 时间、预算、先验承诺、学习偏好——任何限定教学方式的约束]
+
+## Out of scope
+- [TODO: 用户明确不想现在涉及的相邻话题——保护最近发展区]

package/speculo/workflows/doc/_templates/teach-resources-template.md

@@ -0,0 +1,17 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `resources.md`
+
+# [TODO: 学习主题] Resources
+
+## Knowledge
+
+- [TODO: 格式：`[类型: _标题_ — 作者（出处）](链接)`，下一行缩进写用途。优先一手资料、公认专家、同行评审。]
+  [TODO: 覆盖什么、何时取用。]
+
+## Wisdom (Communities)
+
+- [TODO: 格式同 Knowledge。线上论坛、线下课、本地兴趣小组。]
+  [TODO: 用于什么场景的反馈或讨论。]
+
+## Gaps
+[TODO: 若某 Success 项找不到好资源，在此列出。用户选择不加入社区时也在本节记录。]