@namewta/speculo 0.1.20 → 0.1.21

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

@@ -12,152 +12,64 @@ keywords: [review, diff, spec, engineering, standards, security, solid, pr, 审
 
 > **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-review-auth-module`）。审查产物写入 `speculo/.speculo/dev/<change>/`。
 
-## 内置指引
-
-### 何时使用
+## 何时使用
 
 当用户想审查分支、PR、进行中的变更，或要求 `review since <fixed-point>` 时使用。
 
-### 三个审查维度
-
-三个维度是三种独立的"镜头"，**不合并、不重排、不让一个维度的结论掩盖另一个**：
+## 三个审查维度
 
 | 维度 | 问题 | 关注 |
 |------|------|------|
-| **Spec** | 做对了吗？ | 是否忠实实现来源 issue / PRD / spec：缺失需求、范围蔓延、看似实现但有问题的需求 |
-| **Engineering** | 做好了吗？ | 不依赖成文规则的工程质量：SOLID 与架构、安全与可靠性、错误处理、性能、边界、死代码 |
-| **Standards** | 合规吗？ | 是否违反仓库**已记录**的标准：RULES、ADR、CONTRIBUTING、lint / 格式 / 类型配置 |
-
-若缺少 spec，Spec 维度跳过并报告 `no spec available`；若仓库无成文标准，Standards 维度报告检查范围并说明覆盖空白。Engineering 维度始终执行。
-
-### 严重度模型
-
-每条 finding 必须标注严重度：
-
-| 级别 | 名称 | 含义 | 动作 |
-|------|------|------|------|
-| **P0** | Critical | 安全漏洞、数据丢失风险、正确性 bug | 必须阻断合并 |
-| **P1** | High | 逻辑错误、显著 SOLID 违背、性能回退、关键需求缺失 | 合并前应修复 |
-| **P2** | Medium | 代码异味、可维护性隐患、轻微 SOLID 违背、范围蔓延 | 本 PR 修或建后续项 |
-| **P3** | Low | 风格、命名、小建议 | 可选改进 |
-
-### 执行原则
-
-- 用户说的任何东西都是固定点。若用户没有指定固定点，先询问；拿到前不要继续。
-- 比较命令使用三点语法：`git diff <fixed-point>...HEAD`，同时记录 `git log <fixed-point>..HEAD --oneline`。
-- **Worktree 模式**：若当前 change 为 worktree 隔离模式（`.status.json` 的 `worktree_enabled` 为真），fixed point 默认取 `base_branch`，且审查必须完整覆盖 change 分支树 `base_branch..change_branch` 的**每一个 commit**，不能只看最新工作区状态。此时读取 `../../../skills/worktree-isolation/SKILL.md` 的 `references/audit-branch-tree.md`；非 worktree 模式不读取该 skill。
-- **Review-first**：本工作流默认只产出审查结论，**不修改代码**；除非用户在看到 findings 后明确授权修复。
-- **诚实优先**：无法覆盖的区域要显式声明（见 `review-verdict.md` 的 clean-review 要求），不得用"看起来没问题"代替实际检查。
-- 机器已强制的标准（lint / 类型 / 格式）只记录来源，不重复人工检查工具已覆盖的内容。
-- 如果环境支持并行子代理，三个维度应并行执行；如果不支持，按三个独立上下文顺序执行，并在报告中保持分离。
-
-### 渐进披露（Engineering 维度深度清单）
-
-进入 Engineering 维度审查时，按需读取同目录清单：
-
-- `solid-checklist.md`：检查 SOLID 违背与架构异味、给重构启发式时读取。
-- `security-checklist.md`：检查安全漏洞、竞态、密钥、密码学与运行时风险时读取。
-- `code-quality-checklist.md`：检查错误处理、性能 / 缓存、边界条件时读取。
-- `removal-checklist.md`：识别死代码与删除候选、产出删除 / 推迟计划时读取。
-
-### 独立使用
-
-本工作流**零硬依赖**，无需预先执行 dev/01、dev/02、dev/I 等其他工作流即可独立进入。只需用户提供 fixed point（分支/commit/tag）+ 当前 git 仓库即可启动。
-
-**独立进入流程：**
-
-1. **fixed point**：若用户未指定，先询问；拿到前不继续。在 worktree 模式下默认取 `base_branch`。
-2. **change 目录**：若用户未指定 `<change>` 目录，按 `YYYY-MM-DD-<kebab-name>` 格式创建（如 `2026-06-17-review-auth-refactor`），初始化 `.status.json` 并更新 `dev-status.json`。
-3. **信息自采集**：若同 change 目录下无上游产物（PRD、slices、decision-log 等），**自行通过代码库探索采集审查所需上下文**，不要求用户先执行其他工作流：
-   - `git log <fixed-point>..HEAD --oneline` 提取 commit message 中的 issue/PR 引用
-   - 搜索仓库中与变更模块匹配的 spec 文档、README、设计文档
-   - 从代码注释、TODO/FIXME 和 commit message 正文推断需求意图
-   - 搜索 `speculo/.speculo/.config/RULES.md`、`speculo/.speculo/.config/adr/`、`AGENTS.md`、`CONTRIBUTING.md` 获取标准来源
-   - 搜索 `.editorconfig`、`eslint.config.*`、`biome.json`、`prettier.config.*`、`tsconfig.json` 获取机器强制标准
-4. **深度搜索**：Spec 和 Standards 来源仍不足时：
-   - 对关键路径（auth/支付/数据写入/网络）执行额外的代码库考古（`git log -p -- <path>`）
-   - 搜索 `speculo/.speculo/doc/` 和 `speculo/.speculo/archive/` 中的领域文档
-   - 检查变更模块的现有测试文件以推断预期行为
-5. **诚实优先**：找不到 spec 时明确记录 `no spec available`，不编造；找不到成文标准时记录覆盖空白，不把缺失当作"无问题"。Engineering 维度始终执行，不依赖任何外部产物。
-
-### 缺少 change 目录时的自初始化
-
-若当前无对应 change 目录，按以下步骤创建：
-
-1. 从审查意图提取 `<kebab-name>`（如 `review-auth-refactor`、`review-api-changes`）
-2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
-3. 初始化 `.status.json`：
-   ```json
-   {
-     "dev_entry": "dev/R",
-     "current_phase": "1. Review Setup",
-     "phase_history": [],
-     "change_status": "active",
-     "review_fixed_point": null,
-     "review_diff_command": null,
-     "review_axes": ["spec", "engineering", "standards"],
-     "standards_sources": [],
-     "spec_sources": [],
-     "severity_summary": { "p0": 0, "p1": 0, "p2": 0, "p3": 0 },
-     "review_verdict": null,
-     "review_status": "collecting"
-   }
-   ```
-4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组中追加该 change 目录名
+| **Spec** | 做对了吗？ | 是否忠实实现来源 issue / PRD / spec |
+| **Engineering** | 做好了吗？ | 工程质量：SOLID、安全、错误处理、性能、边界、死代码 |
+| **Standards** | 合规吗？ | 是否违反仓库已记录的标准 |
+
+详细严重度模型、独立进入流程与来源深度搜索见 `review-setup.md`。
 
 ## 阶段
 
+| Phase | id | agent | 规范 | 模板 | 产物 |
+|-------|-----|-------|------|------|------|
+| 1. Review Setup | `review-setup` | — | `review-setup.md` | `../_templates/review-sources-template.md` | `review-sources.md` |
+| 2. Multi-Axis Review | `multi-axis-review` | `agents/spec-review-agent.md`、`agents/engineering-review-agent.md`、`agents/standards-review-agent.md` | `review-axes.md` | `../_templates/review-report-template.md` | `review-report.md` |
+| 3. Verdict & Next Steps | `verdict-next-steps` | — | `review-verdict.md` | `../_templates/review-verdict-template.md` | `review-verdict.md` |
+
 ### 1. Review Setup — 固定点、范围与来源收集
-- 规范：`review-setup.md`
-- 模板：`../_templates/review-sources-template.md`
-- 产物：`review-sources.md`
-- 完成准则：
-  - 已记录 fixed point、diff 命令、commit 列表、diff 规模与分批策略
-  - 已列出 standards 来源与 spec 来源，或记录各自缺失
-  - 已标识关键路径（auth / 支付 / 数据写入 / 网络）
-  - `review-sources.md` 无残留 `[TODO:]`
+- id：`review-setup`
+- 完成准则：fixed point、diff 命令、来源清单已记录；`review-sources.md` 无残留 `[TODO:]`
 
 ### 2. Multi-Axis Review — 三维度审查
-- 规范：`review-axes.md`
-- 模板：`../_templates/review-report-template.md`
-- 产物：`review-report.md`
-- 完成准则：
-  - Spec / Engineering / Standards 分区独立呈现，不合并、不重排
-  - 每条 finding 带严重度（P0–P3）、文件/行或 hunk 依据，以及对应 spec / 清单 / 标准引用
-  - `review-report.md` 无残留 `[TODO:]`
+- id：`multi-axis-review`
+- 完成准则：三维度分区独立呈现；每条 finding 带 P0–P3 严重度；`review-report.md` 无残留 `[TODO:]`
 
 ### 3. Verdict & Next Steps — 裁决与后续确认
-- 规范：`review-verdict.md`
-- 模板：`../_templates/review-verdict-template.md`
-- 产物：`review-verdict.md`
-- 完成准则：
-  - 给出整体裁决（APPROVE / REQUEST_CHANGES / COMMENT）与严重度汇总
-  - 完成 clean-review 声明：检查了什么、未覆盖什么、残留风险
-  - 已向用户给出后续选项，未经确认不实施修复
-  - `review-verdict.md` 无残留 `[TODO:]`
+- id：`verdict-next-steps`
+- 完成准则：整体裁决与 clean-review 声明已给出；未经确认不实施修复；`review-verdict.md` 无残留 `[TODO:]`
 
 ## 依赖
 
 - 硬依赖：无；用户提供 fixed point 即可进入
-- 软依赖：无。若同 change 目录下存在其他工作流产物（如 prd.md、slices.md、decision-log.md），可继承其信息增强 Spec 维度审查；缺失时自行采集（commit message、代码注释、项目文档），不阻塞流程。审查完成后是否进入修复（`../03-tdd/03-tdd.md`）或归档（`../04-finalize/04-finalize.md`）由用户决定。
+- 软依赖：同 change 下若有 `prd.md`、`slices.md` 等可继承增强 Spec 维度；缺失时自行采集，不阻塞流程
 
 ## 状态扩展字段
 
-本工作流需在同 change 的 `.status.json` 追加：
-
 - `dev_entry` (string) — 固定为 `dev/R`
-- `review_fixed_point` (string) — 用户提供的比较点
-- `review_diff_command` (string) — 实际使用的 diff 命令
-- `review_axes` (array) — 实际执行的维度，取值自 `spec` | `engineering` | `standards`
-- `standards_sources` (array) — Standards 审查读取的规则来源
-- `spec_sources` (array) — Spec 审查读取的规格来源
-- `severity_summary` (object) — 各严重度 finding 计数：`{ "p0": n, "p1": n, "p2": n, "p3": n }`
-- `review_verdict` (approve | request_changes | comment | null) — 整体裁决
-- `review_status` (collecting | reviewing | judged | completed | blocked) — 审查状态
+- `review_fixed_point` (string)
+- `review_diff_command` (string)
+- `review_axes` (array) — `spec` | `engineering` | `standards`
+- `standards_sources` (array)
+- `spec_sources` (array)
+- `severity_summary` (object) — `{ "p0": n, "p1": n, "p2": n, "p3": n }`
+- `review_verdict` (approve | request_changes | comment | null)
+- `review_status` (collecting | reviewing | judged | completed | blocked)
 
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 完成 setup 后写入 fixed point、diff 命令、`review_axes` 和来源清单。
 - 完成报告后更新 `severity_summary`，置 `review_status: judged`。
-- 完成裁决后写入 `review_verdict`，置 `review_status: completed`；但不自动完成 change —— 是否进入修复（`../03-tdd/03-tdd.md`）、收尾归档（`../04-finalize/04-finalize.md`）或其他动作由用户决定。
+- 完成裁决后写入 `review_verdict`，置 `review_status: completed`；不自动完成 change —— 是否进入修复（`../03-tdd/03-tdd.md`）、收尾（`../04-finalize/04-finalize.md`）由用户决定。
+
+### 缺少 change 目录时
+
+若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。

package/template/workflows/dev/R-review/agents/engineering-review-agent.md

@@ -0,0 +1,33 @@
+---
+id: dev/R-review/engineering-review-agent
+type: agent
+name: Engineering Review Agent
+description: 隔离执行 Engineering 维度审查：做好了吗
+---
+
+## 使命
+
+独立审查 diff 的 Engineering 维度：SOLID、安全、错误处理、性能、边界、死代码。
+
+## 输入契约
+
+- change 路径：`speculo/.speculo/dev/<change>/`
+- `current_phase` / phase-id：`multi-axis-review`
+- 上游产物：`review-sources.md`
+- 清单：`../solid-checklist.md`、`../security-checklist.md`、`../code-quality-checklist.md`、`../removal-checklist.md`
+
+## 执行规范
+
+- 使用 `review-sources.md` 中的 diff 命令。
+- Engineering 维度始终执行，不依赖外部 spec。
+- 按需读取同目录清单；每条 finding 带 P0–P3 严重度与清单引用。
+- 产出写入 `review-report.md` 的 Engineering 分区。
+
+## 产物与状态
+
+- 产物：`review-report.md`（Engineering 分区）
+- `.status.json`：追加 `review_axes` 含 `engineering`；更新 `severity_summary`
+
+## 边界
+
+- 只写 Engineering 分区；不修改代码；不写 `change_status`；不产出最终 verdict。

package/template/workflows/dev/R-review/agents/spec-review-agent.md

@@ -0,0 +1,34 @@
+---
+id: dev/R-review/spec-review-agent
+type: agent
+name: Spec Review Agent
+description: 隔离执行 Spec 维度审查：做对了吗
+---
+
+## 使命
+
+独立审查 diff 的 Spec 维度：是否忠实实现来源 issue / PRD / spec。
+
+## 输入契约
+
+- change 路径：`speculo/.speculo/dev/<change>/`
+- `current_phase` / phase-id：`multi-axis-review`
+- 上游产物：`review-sources.md`（fixed point、diff 命令、spec 来源）
+- 规范：`../review-axes.md`（Spec 分区）
+
+## 执行规范
+
+- 使用 `review-sources.md` 中的 diff 命令与 spec 来源。
+- 无 spec 时报告 `no spec available`，不编造需求。
+- 每条 finding 带 P0–P3 严重度、文件/行依据与 spec 引用。
+- 产出写入 `review-report.md` 的 Spec 分区（与 Engineering、Standards 分区独立）。
+
+## 产物与状态
+
+- 产物：`review-report.md`（Spec 分区）
+- `.status.json`：追加 `review_axes` 含 `spec`；更新 `severity_summary`
+
+## 边界
+
+- 只写 Spec 分区；不合并或重排其他维度 findings。
+- 不修改代码；不写 `change_status`；不产出最终 verdict。

package/template/workflows/dev/R-review/agents/standards-review-agent.md

@@ -0,0 +1,34 @@
+---
+id: dev/R-review/standards-review-agent
+type: agent
+name: Standards Review Agent
+description: 隔离执行 Standards 维度审查：合规吗
+---
+
+## 使命
+
+独立审查 diff 的 Standards 维度：是否违反仓库已记录的标准。
+
+## 输入契约
+
+- change 路径：`speculo/.speculo/dev/<change>/`
+- `current_phase` / phase-id：`multi-axis-review`
+- 上游产物：`review-sources.md`（standards 来源清单）
+- 规范：`../review-axes.md`（Standards 分区）
+
+## 执行规范
+
+- 使用 `review-sources.md` 中的 diff 命令与 standards 来源。
+- 无成文标准时报告覆盖空白，不把缺失当作无问题。
+- 机器已强制的标准（lint / 类型）只记录来源，不重复人工检查。
+- 每条 finding 带 P0–P3 严重度与标准引用。
+- 产出写入 `review-report.md` 的 Standards 分区。
+
+## 产物与状态
+
+- 产物：`review-report.md`（Standards 分区）
+- `.status.json`：追加 `review_axes` 含 `standards`；更新 `severity_summary`
+
+## 边界
+
+- 只写 Standards 分区；不修改代码；不写 `change_status`；不产出最终 verdict。

package/template/workflows/dev/R-review/review-setup.md

@@ -6,6 +6,37 @@
 - 当前 git 仓库
 - 当前 change 目录：`speculo/.speculo/dev/<change>/`
 
+## 严重度模型
+
+每条 finding 必须标注严重度：
+
+| 级别 | 名称 | 含义 | 动作 |
+|------|------|------|------|
+| **P0** | Critical | 安全漏洞、数据丢失风险、正确性 bug | 必须阻断合并 |
+| **P1** | High | 逻辑错误、显著 SOLID 违背、性能回退、关键需求缺失 | 合并前应修复 |
+| **P2** | Medium | 代码异味、可维护性隐患、轻微 SOLID 违背、范围蔓延 | 本 PR 修或建后续项 |
+| **P3** | Low | 风格、命名、小建议 | 可选改进 |
+
+## 执行原则
+
+- 用户说的任何东西都是固定点。若用户没有指定固定点，先询问；拿到前不要继续。
+- 比较命令使用三点语法：`git diff <fixed-point>...HEAD`，同时记录 `git log <fixed-point>..HEAD --oneline`。
+- **Worktree 模式**：若当前 change 为 worktree 隔离模式（`.status.json` 的 `worktree_enabled` 为真），fixed point 默认取 `base_branch`，且审查必须完整覆盖 change 分支树 `base_branch..change_branch` 的**每一个 commit**。此时读取 `../../../skills/worktree-isolation/SKILL.md` 的 `references/audit-branch-tree.md`。
+- **Review-first**：本工作流默认只产出审查结论，**不修改代码**；除非用户在看到 findings 后明确授权修复。
+- **诚实优先**：无法覆盖的区域要显式声明（见 `review-verdict.md` 的 clean-review 要求）。
+- 机器已强制的标准（lint / 类型 / 格式）只记录来源，不重复人工检查。
+- 如果环境支持并行子代理，三个维度应并行执行；否则按三个独立上下文顺序执行。
+
+## 独立进入流程
+
+本工作流**零硬依赖**。只需用户提供 fixed point + 当前 git 仓库即可启动。
+
+1. **fixed point**：若用户未指定，先询问；worktree 模式下默认取 `base_branch`。
+2. **change 目录**：若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。
+3. **信息自采集**：若同 change 下无上游产物，按下方「来源深度搜索」自行采集审查上下文。
+4. **深度搜索**：Spec 和 Standards 来源仍不足时，对关键路径执行额外考古；检查测试文件推断预期行为。
+5. **诚实优先**：找不到 spec 时记录 `no spec available`；找不到成文标准时记录覆盖空白。Engineering 维度始终执行。
+
 ## 独立进入时的来源深度搜索
 
 当本工作流独立进入（无上游 PRD、slices、decision-log 等产物）时，在收集 spec 和 standards 来源时执行以下扩展搜索。**不要求用户先执行 dev/01、dev/02 或其他工作流。**
@@ -57,7 +88,14 @@
    - `.editorconfig`、`eslint.config.*`、`biome.json`、`prettier.config.*`、`tsconfig.json`
    - 全部缺失时记录覆盖空白说明
 7. 机器强制的标准只记录来源，不重复检查工具已覆盖的内容。
-8. Engineering 维度不需要外部来源，但记录将依据同目录的 `solid-checklist.md`、`security-checklist.md`、`code-quality-checklist.md`、`removal-checklist.md`。
+8. Engineering 维度不需要外部来源，但记录将依据同目录的 `solid-checklist.md`、`security-checklist.md`、`code-quality-checklist.md`、`removal-checklist.md`（进入 Engineering 审查时按需读取）。
+
+## 渐进披露（Engineering 维度深度清单）
+
+- `solid-checklist.md`：SOLID 违背与架构异味
+- `security-checklist.md`：安全漏洞、竞态、密钥、密码学
+- `code-quality-checklist.md`：错误处理、性能、边界条件
+- `removal-checklist.md`：死代码与删除候选
 
 ## 边界
 

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

@@ -86,7 +86,7 @@ P1  phase1-xxx  切片名称  依赖 P0
 [TODO: 汇总影响全局或跨切片的技术选型与取舍，如方案选择（工具类 vs 正则）、字段复用/新建决策、SQL 追加规则等。防止下游对同一问题反复争论。单文件小改可删除本节。]
 
 ## 6. 风险与回滚
-[TODO: 条件段——本期涉及删除/数据迁移/外部副作用/高耦合时填：风险 / 触发条件 / 缓解 / 回滚 表；有 prd-overview.md 风险则继承细化。纯增量小改可删除本节。]
+[TODO: 条件段——本期涉及删除/数据迁移/外部副作用/高耦合时填：风险 / 触发条件 / 缓解 / 回滚 表；有 overview.md 风险则继承细化。纯增量小改可删除本节。]
 
 ## 7. 退役清单
 [TODO: 条件段——仅当删除既有能力时填：项 / 处置 / 验证 表，逐条记录被删或被迁内容及其去向。无删除则删除本节。]

package/template/workflows/dev/_templates/{prd-overview-template.md → overview-template.md}

@@ -1,6 +1,5 @@
 > **服务工作流：** `../02-prd/02-prd.md`
 > **产物文件名：** `overview.md`
-> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Overview
 

package/template/workflows/doc/AGENTS.md

@@ -39,7 +39,7 @@ keywords: [doc, writing, article, fragments, edit, agents, 文档, 写作]
 2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
 3. 若没有 active change，按用户意图创建新的 doc change。**以下三步为原子操作，不可跳过，前一步失败时停止后续并报告：**
    - **3a. 创建 change 目录** —— `speculo/.speculo/doc/<YYYY-MM-DD>-<kebab-name>/`（使用当前日期，`<kebab-name>` 从用户意图提取，不超过 5 个词）。
-   - **3b. 写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，按 `docs/persistence-contract.md` §2.2 最小初始化模板填入所有必填字段（`name`、`category: "doc"`、`change_status: "active"`、`created_at`、`updated_at`、`current_phase: "00-init"`、`phase_history`）。
+   - **3b. 写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，按 `../../skills/speculo-write/references/persistence-contract-sop.md` 最小初始化模板填入所有必填字段（`name`、`category: "doc"`、`change_status: "active"`、`created_at`、`updated_at`、`current_phase: "00-init"`、`phase_history`）。
    - **3c. 更新 `doc-status.json`** —— 读取 `speculo/.speculo/doc-status.json`，在 `active[]` 中追加该 change 的索引条目（`name`、`current_phase: "00-init"`、`updated_at`），写回文件。
    - 以上三步全部成功后，方可继续推荐入口。
 4. 推荐入口时优先使用用户显式别名；没有别名时按用户意图推荐一个横向 workflow。
@@ -64,9 +64,17 @@ keywords: [doc, writing, article, fragments, edit, agents, 文档, 写作]
 - `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
 - 推荐下一步入口和原因
 
+## 续跑协议
+
+1. 读取 change 目录下 `.status.json` 的 `current_phase` 与 `phase_history`。
+2. 跳过 `status: completed` 的 phase；从 `in-progress`、`blocked` 或首个 `pending` phase 继续。
+3. 根据 `current_phase` 匹配 workflow 入口 `## 阶段` 中的机器 id，只读取对应 phase 文件与模板。
+4. 首个 workflow 进入 change 时写入 `execution_mode`（使用入口声明的执行模式名或用户指定别名）。
+5. 不得因续跑而重复创建 change 或重写已完成的 phase 产物。
+
 ## 完成与状态更新
 
 - 所有 doc workflow 必须维护同一 change 的 `.status.json`。
 - 进入 phase 时更新 `current_phase`，并在 `phase_history` 追加 `in-progress` 记录。
 - phase 完成时写入 `completed_at` 和 `status: completed`。
-- 用户确认文章、素材采集或编辑边界完成后，才把 `change_status` 置为 `completed`。
+- 用户确认文章、素材采集或编辑边界完成后，调用 `../../commands/archive.md` 归档 change；不得自行写入 `change_status: completed`（doc 分类无 finalize workflow）。

package/template/workflows/doc/B-writing-beats/B-writing-beats.md

@@ -76,4 +76,4 @@ beat 是旅程中的一个动作：铺开一个场景、落下一个观点、提
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 每次写入 beat 后更新 `beat_count`、`current_beat_status` 和 `updated_at`。
-- 文章自然结束且用户确认后，可把 `change_status` 置为 `completed`。
+- 文章自然结束且用户确认后，调用 `../../commands/archive.md` 归档 change；不得自行写入 `change_status: completed`。

package/template/workflows/doc/E-edit-article/E-edit-article.md

@@ -76,4 +76,4 @@ keywords: [edit, article, revise, clarity, draft, 编辑, 修订]
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 完成 edit plan 后更新 `section_count` 和 `edit_status`。
 - 每节重写后更新 `updated_at` 和 `edit_status`。
-- 用户确认 edited article 完成后，可把 `change_status` 置为 `completed`。
+- 用户确认 edited article 完成后，调用 `../../commands/archive.md` 归档 change；不得自行写入 `change_status: completed`。

package/template/workflows/doc/S-writing-shape/S-writing-shape.md

@@ -78,4 +78,4 @@ keywords: [shape, article, markdown, draft, writing, 塑形]
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 每次写入块后更新 `format_decisions`、`writing_status` 和 `updated_at`。
-- 文章完成由用户决定；用户确认完成后，可把 `change_status` 置为 `completed`。
+- 文章完成由用户决定；用户确认完成后，调用 `../../commands/archive.md` 归档 change；不得自行写入 `change_status: completed`。

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

@@ -8,140 +8,57 @@ keywords: [teach, lesson, learning, glossary, 教学, 课程, 术语, 学习]
 
 # Teaching Design 工作流执行指引
 
-本工作流用于在项目内围绕一个学习主题，设计并交付交互式教学体验。它是 `doc/T` 入口，覆盖从使命确立到课程产出、参考文档和洞察记录的完整链路。
+本工作流是 `doc/T` 入口：围绕学习主题设计交互式教学体验（使命→资源→课程→参考→记录）。
 
-## 内置指引
+> **产物目录：** `speculo/.speculo/doc/<change>/`。`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。
 
-### 核心理念
+## 核心理念
 
-深度学习需要三样东西：
+深度学习需要 Knowledge（高质量资源）、Skills（交互式课程）与 Wisdom（实践互动）。留存设计原则：retrieval practice、spacing、interleaving。每节课短小、给一个具体胜利，控制在学习者工作记忆容量内。
 
-- **Knowledge（知识）** — 从高质量、高信任度资源获取
-- **Skills（技能）** — 通过你设计的高度相关交互式课程获得
-- **Wisdom（智慧）** — 来自与其他学习者和实践者的互动
-
-获取知识时，难度是敌人——它会吃掉理解所需的工作记忆。练习技能时，难度是工具——有努力的提取才能建立长期留存。
-
-### 留存设计原则
-
-- **Retrieval practice**：让用户从记忆中回忆，而非重新阅读
-- **Spacing**：把练习分散到多节课，不要集中轰炸
-- **Interleaving**：在技能练习中混合不同但相关的主题
-
-每节课应该短小精悍，在很短时间内可完成。学习者工作记忆很有限，必须控制在容量内。但每节课应该给用户一个具体的小胜利。
-
-### 最近发展区
-
-每节课用户都应该感觉被挑战得「刚好够」。判断最近发展区的方法：
-
-1. 读取 `learning-records/`，了解用户已知什么
-2. 基于使命判断下一个该教什么
-3. 教能放进最近发展区的最相关内容
-
-### Lesson 铁律
-
-一节 lesson 是自包含的单个 HTML 文件，保存为 `speculo/.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>
-```
+Lesson 铁律与 HTML 课程结构见 `teach-lesson.md` 与 `../_templates/teach-lesson-html-template.md`。
 
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `speculo/.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-teach-react-basics`）。
+| Phase | id | 规范 | 模板 | 产物 |
+|-------|-----|------|------|------|
+| 1. Mission Setup | `mission-setup` | `teach-mission.md` | `../_templates/teach-mission-template.md` | `mission.md` |
+| 2. Resources Curation | `resources-curation` | `teach-resources.md` | `../_templates/teach-resources-template.md` | `resources.md` |
+| 3. Lesson Design | `lesson-design` | `teach-lesson.md` | `../_templates/teach-lesson-html-template.md` | `lessons/<编号>.html` |
+| 4. Lesson Wrap | `lesson-wrap` | `teach-lesson-wrap.md` | glossary + learning-record 模板 | `reference/<编号>.html` 等 |
+
+Phase 3 ↔ 4 为紧密循环：每节课程完成后立即收尾。`current_loop` 映射：`mission-setup` | `resources-curation` | `lesson-design` | `lesson-wrap`。
 
 ### 1. Mission Setup — 确立学习使命
-- 规范：`teach-mission.md`
-- 模板：`../_templates/teach-mission-template.md`
-- 产物：`mission.md`
-- 完成准则：
-  - 已追问出具体、可观测的成功标准（非「想了解 X」而是「能做 Y」）
-  - Why / Success / Constraints / Out of scope 四段均已填写
-  - `mission.md` 无残留 `[TODO:]`
+- id：`mission-setup`
+- 完成准则：`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
+- id：`resources-curation`
+- 完成准则：`resources.md` 无残留 `[TODO:]`；至少一条高信任度资源
+
+### 3. Lesson Design — 设计一节交互式课程
+- id：`lesson-design`
+- 完成准则：课程关联 `mission.md`；编号递增
 
 ### 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`（若用户表达了教学偏好）
+- id：`lesson-wrap`
+- 完成准则：参考文档与 GLOSSARY 已更新
 
 ## 依赖
 
-- 硬依赖：Phase 1 → Phase 2，使命未确立前不得策展资源
-- 软依赖：Phase 2 → Phase 3，建议先有资源再设计课程
-- Phase 3 ↔ Phase 4 为紧密循环：每节课程完成后立即收尾
+- 硬依赖：Phase 1 → Phase 2
+- 软依赖：Phase 2 → Phase 3
 
 ## 状态扩展字段
 
-本工作流需在同 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) — 当前循环位置
+- `mission_status` (drafting | confirmed)
+- `resource_count`、`lesson_count`、`reference_count`、`learning_record_count`、`glossary_term_count` (number)
+- `current_loop` (mission-setup | resources-curation | lesson-design | 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/.speculo/.config/LESSONS.md`。
-- NOTES.md 作为教学偏好暂存区，AI 在后续课程设计中应参考其中记录。
+- Phase 3-4 循环时更新 `lesson_count` 等计数。
+- 用户声明学习目标全部达成后，调用 `../../commands/archive.md` 归档 change；不得自行写入 `change_status: completed`。

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

@@ -21,7 +21,7 @@
 1. **用户展示了非显而易见的真正理解** — 不是仅仅接触过，而是有证据表明能正确使用这个概念。这为后续教学设定了新底线。
 2. **用户披露了先验知识** — 「我已经知道 X」。记录下来避免后续重新教。同时记录声称的深度。
 3. **一个误解被纠正** — 用户之前相信了错误的东西，现在明白了为什么。高价值：预测后续相关主题的绊脚石。
-4. **使命因学习而改变** — 用户发现自己在意的和最初想的不同。交叉引用 [[mission.md]] 并更新它。
+4. **使命因学习而改变** — 用户发现自己在意的和最初想的不同。交叉引用 `mission.md` 并更新它。
 
 ### 不写的情况
 

package/template/workflows/doc/_templates/teach-lesson-html-template.md

@@ -0,0 +1,24 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `lessons/<编号>.html`
+
+```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>
+```