@namewta/speculo 0.1.21 → 0.2.0

package/template/workflows/dev/02-prd/02-prd.md

@@ -1,70 +0,0 @@
----
-id: dev/prd
-category: dev
-name: PRD
-description: 通过 zoom-out 全景理解与 to-prd 综合产出开发 PRD
-keywords: [prd, zoom-out, 需求, 计划]
----
-
-# PRD 工作流执行指引
-
-本工作流用于把已知上下文综合为当前 Speculo change 内的 overview 和 PRD。zoom-out 全景理解与 PRD 综合能力已内置在本 workflow 目录中。
-
-> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。产物写入 `speculo/.speculo/dev/<change>/`。
-
-## 内置指引
-
-### Zoom Out
-
-当 agent 对某段代码或业务区域不熟悉，需要先建立全局视角再继续 PRD、设计、诊断或实现时使用。用项目领域术语表给出相关模块、调用者、关键边界、上下游依赖和需要进一步确认的问题。
-
-### PRD Synthesis
-
-当 dev workflow 已完成足够上下文探索，需要把当前对话和代码理解沉淀成 PRD 时使用。不要重复访谈已明确的信息；综合当前对话、代码库事实、领域术语、ADR、模块候选和测试目标。
-
-PRD 综合统一使用 `speculo/.speculo/.config/context/CONTEXT.md` 的通用语言；若 PRD 引入或锐化了 CONTEXT 中尚不存在的领域术语，按横向工作流 `../M-domain-modeling/M-domain-modeling.md` 主动沉淀（用户确认后写入 `.config/context/`），不要让术语只活在 PRD 里。
-
-PRD 只写入 `speculo/.speculo/dev/<change>/prd.md`，overview 只写入 `speculo/.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-## 阶段
-
-### 1. Zoom Out — 全景理解
-- 规范：`prd-zoom-out.md`
-- 模板：`../_templates/overview-template.md`
-- 产物：`overview.md`
-- 完成准则：
-  - 已说明相关模块、调用者、边界和未知点
-  - `overview.md` 无残留 `[TODO:]`
-
-### 2. PRD Synthesis — PRD 综合
-- 规范：`prd-synthesis.md`
-- 模板：`../_templates/prd-template.md`
-- 产物：`prd.md`
-- 完成准则：
-  - PRD 包含问题、方案、用户故事、实现决策、测试决策、范围边界
-  - 已确认模块候选和测试目标
-  - `prd.md` 无残留 `[TODO:]`
-
-## 依赖
-
-- 软依赖：`../01-grill-with-docs/01-grill-with-docs.md`，scope: same-change
-- 硬依赖：无
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/02`
-- `embedded_guides` (array) — 包含 `zoom-out`、`to-prd`
-- `prd_slug` (string) — PRD 短 slug
-- `module_candidates` (array) — 候选模块或边界
-- `test_targets` (array) — 用户确认的测试目标
-- `issue_tracker_mode` (disabled | local-only | publish-requested | published) — issue tracker 使用状态
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 默认把 PRD 写入当前 change 的 `prd.md`；不默认写项目根下的任意规划文档。
-- 本 workflow 完成后不自动完成 change；默认移交 `../I-to-issues/I-to-issues.md` 或 `../03-tdd/03-tdd.md`。

package/template/workflows/dev/02-prd/prd-synthesis.md

@@ -1,30 +0,0 @@
-# PRD Synthesis Phase
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/overview.md`
-- 可选的 `context-map.md`、`decision-log.md`、用户故事或 issue
-- `02-prd.md` 中的 PRD Synthesis 内置指引
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/prd.md`，由 `../_templates/prd-template.md` 填写
-
-## 填写引导
-
-1. 遵循 `02-prd.md` 的 PRD Synthesis 内置指引。
-2. 综合已有上下文，不重复访谈已明确的信息。
-3. 与用户确认模块候选和需要测试的行为。
-4. 默认只生成本地 `prd.md`；只有 tracker 已配置且用户明确要求时才发布 issue。
-5. PRD 中避免易过时的具体文件路径和代码片段，除非它们表达不可替代的决策。
-
-## 边界
-
-- 不进行 issue 切片；切片由 `../I-to-issues/I-to-issues.md` 负责。
-- 不修改业务代码。
-- 不把 change 标记为 completed。
-
-## 完成准则
-
-- `prd.md` 无残留 `[TODO:]`
-- `test_targets`、`prd_slug`、`issue_tracker_mode` 已写入 `.status.json`

package/template/workflows/dev/02-prd/prd-zoom-out.md

@@ -1,29 +0,0 @@
-# Zoom Out Phase
-
-## 输入
-
-- 用户目标、已有 `context-map.md` 或 `decision-log.md`
-- 相关代码区域、架构文档、ADR 和配置
-- `02-prd.md` 中的 Zoom Out 内置指引
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/overview.md`，由 `../_templates/overview-template.md` 填写
-
-## 填写引导
-
-1. 遵循 `02-prd.md` 的 Zoom Out 内置指引。
-2. 用项目领域术语说明相关模块和调用者。
-3. 标明现有行为、缺失能力、接口边界、上下游依赖和风险。
-4. 输出服务于 PRD 综合的事实，不提前写实现步骤。
-
-## 边界
-
-- 不发布 issue。
-- 不修改代码。
-- 不创建 PRD；PRD 留到下一阶段。
-
-## 完成准则
-
-- `overview.md` 无残留 `[TODO:]`
-- `.status.json` 已记录 `module_candidates`

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

@@ -1,55 +0,0 @@
----
-id: dev/tdd
-category: dev
-name: TDD Implementation
-description: 按垂直切片执行红绿重构，实现功能或回归修复
-keywords: [tdd, implement, red-green-refactor, 实现, 测试]
----
-
-# TDD Implementation 工作流执行指引
-
-本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 细节见同目录 phase 文件；设计词汇统一引用 `../../../vendor/codebase-design/SKILL.md`。
-
-> **产物目录：** `speculo/.speculo/dev/<change>/tdd/<phase-id>/`。`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。
-
-## 阶段
-
-| Phase | id | agent | 规范 | 模板 | 产物 |
-|-------|-----|-------|------|------|------|
-| 1. TDD Plan | `tdd-plan` | `agents/tdd-plan-agent.md` | `tdd-plan.md` | `../_templates/tdd-plan-template.md` | `tdd/<phase-id>/tdd-plan.md` |
-| 2. Slice Loop | `slice-loop` | `agents/tdd-implement-agent.md` | `tdd-loop.md` | `../_templates/tdd-log-template.md` | `tdd/<phase-id>/implementation-log.md` |
-| 3. Finish | `tdd-finish` | `agents/tdd-finish-agent.md` | `tdd-finish.md` | `../_templates/tdd-verification-template.md` | `tdd/<phase-id>/verification.md` |
-
-### 1. TDD Plan — 行为与接口计划
-- id：`tdd-plan`
-- 完成准则：公共接口与测试优先级已确认；`tdd-plan.md` 无残留 `[TODO:]`
-
-### 2. Slice Loop — 红绿重构循环
-- id：`slice-loop`
-- 完成准则：每切片有 RED/GREEN/REFACTOR 记录；`implementation-log.md` 无残留 `[TODO:]`
-
-### 3. Finish — 验证与收尾
-- id：`tdd-finish`
-- 完成准则：验证已运行；slices 状态已翻转（若有）；`verification.md` 无残留 `[TODO:]`
-
-slices 消费契约、Git 基线、XML 阶段状态见 `tdd-plan.md` 与 `tdd-finish.md`。
-
-## 依赖
-
-- 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
-- 硬依赖：无
-
-## 状态扩展字段
-
-- `dev_entry` (string) — 固定为 `dev/03`
-- `tdd_phase_id` (string)
-- `slice_source` (prd | issues | diagnosis | user-request)
-- `red_green_refactor_cycles` (array)
-- `verification_commands` (array)
-- `implementation_status` (planned | in-progress | verified | blocked)
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- Finish 验证通过后把 slices 中该阶段 `status` 由 `未开始` 置为 `已实现`（无 slices 则跳过）。
-- 全部实现边界完成并验证后，移交 `../04-finalize/04-finalize.md` 或 `../R-review/R-review.md`；不得自行写入 `change_status: completed`。

package/template/workflows/dev/03-tdd/agents/tdd-finish-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/03-tdd/tdd-finish-agent
-type: agent
-name: TDD Finish Agent
-description: 隔离执行 Finish phase：验证收尾与 slices 状态翻转
----
-
-## 使命
-
-完成 TDD 收尾验证，产出 `verification.md`，并将 slices 中对应阶段标记为 `已实现`。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`tdd-finish`
-- 上游产物：`tdd/<phase-id>/implementation-log.md`、`tdd/<phase-id>/tdd-plan.md`、`slices.md`（若存在）
-- 模板：`../_templates/tdd-verification-template.md`
-
-## 执行规范
-
-- 按 `../tdd-finish.md` 运行验证命令，记录完整输出。
-- 运行 slices 验收切片；删除型切片须含残留扫描证据。
-- 验证通过后把 `slices.md` 中 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 slices 则跳过）。
-- 产物写入 `speculo/.speculo/dev/<change>/tdd/<phase-id>/verification.md`。
-
-## 产物与状态
-
-- 产物：`tdd/<phase-id>/verification.md`
-- `.status.json`：更新 `current_phase: tdd-finish`、`verification_commands`、`implementation_status: verified`
-
-## 边界
-
-- 不越过本 phase；不把 slices 置为 `已验证`（属 `dev/04`）。
-- 不写 `change_status`；完成后移交 `../../04-finalize/04-finalize.md` 或 `../../R-review/R-review.md`。

package/template/workflows/dev/03-tdd/agents/tdd-implement-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/03-tdd/tdd-implement-agent
-type: agent
-name: TDD Implement Agent
-description: 隔离执行 Slice Loop phase：红绿重构循环与测试实现
----
-
-## 使命
-
-在当前 change 的 `<phase-id>` 下执行红绿重构循环，产出 `implementation-log.md` 与对应代码变更。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`slice-loop`
-- 上游产物：`tdd/<phase-id>/tdd-plan.md`、`slices.md`（若存在）
-- 模板：`../_templates/tdd-log-template.md`
-
-## 执行规范
-
-- 按 `../tdd-loop.md` 执行 RED → GREEN → REFACTOR 循环。
-- 测试设计读 `../tests.md`；mock 边界读 `../mocking.md`；重构读 `../refactoring.md`。
-- 守护 slices 契约：保留/不动清单、现场核对行号、横切铁律见 `../../I-to-issues/issues-slices.md`。
-- 产物写入 `speculo/.speculo/dev/<change>/tdd/<phase-id>/implementation-log.md`。
-
-## 产物与状态
-
-- 产物：`tdd/<phase-id>/implementation-log.md`、对应源代码与测试
-- `.status.json`：更新 `current_phase: slice-loop`、`red_green_refactor_cycles`、`implementation_status: in-progress`
-
-## 边界
-
-- 不越过本 phase；不执行 Finish 验证或 slices 状态翻转。
-- 不写 `change_status`。

package/template/workflows/dev/03-tdd/agents/tdd-plan-agent.md

@@ -1,34 +0,0 @@
----
-id: dev/03-tdd/tdd-plan-agent
-type: agent
-name: TDD Plan Agent
-description: 隔离执行 TDD Plan phase：确认公共接口、行为与测试优先级
----
-
-## 使命
-
-为当前 change 的单个 `<phase-id>` 产出 `tdd-plan.md`，不进入实现循环。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`tdd-plan`
-- 上游产物：`slices.md`（若存在）、`prd.md` / `overview.md`、诊断结论或用户任务描述
-- 模板：`../_templates/tdd-plan-template.md`
-
-## 执行规范
-
-- 读取 `../03-tdd.md` 的 Git 基线要求，先记录分支与 dirty 状态。
-- 按 `../tdd-plan.md` 填写行为与接口计划；slices 消费契约见 `../tdd-plan.md` 与 `../../I-to-issues/issues-slices.md`。
-- 设计词汇引用 `../../../../vendor/codebase-design/SKILL.md`，不复制正文。
-- 产物写入 `speculo/.speculo/dev/<change>/tdd/<phase-id>/tdd-plan.md`。
-
-## 产物与状态
-
-- 产物：`tdd/<phase-id>/tdd-plan.md`
-- `.status.json`：更新 `current_phase: tdd-plan`、`tdd_phase_id`、`implementation_status: planned`
-
-## 边界
-
-- 不越过本 phase；不写测试实现、不修改源代码。
-- 不写 `change_status`；不执行 Slice Loop 或 Finish。

package/template/workflows/dev/03-tdd/mocking.md

@@ -1,43 +0,0 @@
-# Mock 边界与可 Mock 性
-
-> **依赖类别**（进程内 / 本地可替换 / 端口与适配器 / 真正外部）与「在接缝处注入端口、生产用真实适配器、测试用内存或 mock 适配器」的判定，是设计词汇的一部分，见单一事实源 `../../../vendor/codebase-design/DEEPENING.md`。本文只覆盖**写测试时**的 mock 取舍与 SDK 风格接口。
-
-## 只在系统边界处 mock
-
-- 外部 API（支付、邮件等）
-- 数据库（有时——优先考虑测试数据库 / 本地可替换实现）
-- 时间 / 随机性
-- 文件系统（有时）
-
-不要 mock：
-
-- 你自己的类 / 模块
-- 内部协作者
-- 任何你能控制的东西
-
-> 依赖注入（接受依赖而非内部创建）是让边界可 mock 的前提；该原则见 `../../../vendor/codebase-design/SKILL.md`「为可测试性设计」，本文不复制。
-
-## 优先 SDK 风格接口，而非通用 fetcher
-
-为每个外部操作创建专用函数，而不是一个带条件逻辑的通用函数：
-
-```typescript
-// 好：每个函数都可以独立 mock
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// 坏：mock 时需要在内部写条件逻辑
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-SDK 方式意味着：
-
-- 每个 mock 返回一种特定的数据结构
-- 测试准备中不需要条件逻辑
-- 更容易看出测试覆盖了哪些端点
-- 每个端点都有类型安全

package/template/workflows/dev/03-tdd/refactoring.md

@@ -1,10 +0,0 @@
-# 重构候选
-
-TDD 循环后，寻找以下问题：
-
-- **重复** → 提取函数/类
-- **长方法** → 拆分为私有辅助方法（保持测试只测公共接口）
-- **浅模块** → 合并或加深
-- **特性嫉妒（Feature Envy）** → 把逻辑移到数据所在的地方
-- **基本类型偏执** → 引入值对象
-- **现有代码**被新代码揭示出问题

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

@@ -1,34 +0,0 @@
-# Finish Phase
-
-## 输入
-
-- `implementation-log.md`
-- 项目验证命令和变更 diff
-- `03-tdd.md` 中的内置 TDD 指引和同目录 `refactoring.md`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/tdd/<phase-id>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
-
-## 填写引导
-
-1. 运行与变更相关的测试、类型检查、lint 或构建命令。
-2. **运行本切片「验收切片」**：执行切片记录的验收命令/步骤；**删除型切片须做残留扫描**（`grep -rn "<符号>" <范围>` 应 0 命中），记录证据。
-3. **核对「保留/不动」未被破坏**：确认实现未触碰切片冻结的常量 / 共享依赖 / 邻近功能。
-4. 记录无法运行的命令和阻塞原因。
-5. 搜索临时调试标记、一次性脚本和推测性实现。
-6. 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「phase 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 slices 则跳过）。
-7. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
-
-## 边界
-
-- 不自动归档 change；归档由 `commands/archive.md` 负责。
-- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
-
-## 完成准则
-
-- 本切片「验收切片」已运行通过（删除型切片含残留扫描 `grep` 0 命中），并在 `verification.md` 留证
-- 「保留/不动」清单经核对未被破坏
-- 多阶段 slices：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 slices 则不适用）
-- `verification.md` 无残留 `[TODO:]`
-- `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

package/template/workflows/dev/03-tdd/tdd-loop.md

@@ -1,36 +0,0 @@
-# Slice Loop Phase
-
-## 输入
-
-- `tdd-plan.md`
-- `slices.md` 或用户确认的切片顺序
-- `tdd-plan.md` 中记录的执行前 git 基线；每轮开始前核对本轮触及文件是否存在未知改动
-- `03-tdd.md` 中的内置 TDD 指引和同目录辅助文档
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/tdd/<phase-id>/implementation-log.md`，由 `../_templates/tdd-log-template.md` 填写
-- 可选：`tdd/<phase-id>/tasks/00-INDEX.md` 与 `tdd/<phase-id>/tasks/TNN.md`，由 workflow 自治创建
-
-## 填写引导
-
-1. 每次只选择一个切片和一个行为。
-2. RED：写一个通过公共接口验证行为的失败测试。
-3. GREEN：写最少实现使当前测试通过。
-4. REFACTOR：只在绿色状态下整理设计。
-5. 每轮记录测试名、失败信号、实现摘要、重构摘要、验证命令和 git 状态变化摘要。
-6. 每轮检查：测试描述行为而非实现；测试只使用公共接口；测试能经受内部重构；代码是当前测试的最少实现；没有添加推测性功能；**未触碰本切片「保留/不动」清单**；引用代码以现场为准（不照搬切片行号）；未覆盖未知 dirty/staged 改动。
-
-## 边界
-
-- 不预实现未来切片。
-- 不使用内部实现细节作为主要断言。
-- 不在 RED 状态下重构。
-- 不触碰本切片「保留/不动」清单（冻结常量 / 共享依赖 / 邻近功能）。
-- 不回退、覆盖或格式化与本切片无关的已有改动。
-
-## 完成准则
-
-- 每个完成切片都有 RED/GREEN/REFACTOR 记录
-- `implementation-log.md` 无残留 `[TODO:]`
-- `.status.json` 已追加 `red_green_refactor_cycles`

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

@@ -1,37 +0,0 @@
-# TDD Plan Phase
-
-## 输入
-
-- `prd.md`、`slices.md`、`diagnosis.md` 或用户明确任务
-- 多阶段：本阶段对应切片的 **保留/不动**、**关键核实结论**、**验收切片** 与 §4 横切铁律（`slices.md`）
-- 项目测试命令、现有测试样式和公共接口
-- 当前仓库 git 基线：分支、`git status --short --branch`、`git diff --stat`、`git diff --cached --stat`
-- `03-tdd.md` 中的内置 TDD 指引（含「消费 slices 切片契约」）和同目录辅助文档
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/tdd/<phase-id>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写（`<phase-id>` 见 `03-tdd.md`「TDD 产物目录与阶段标识」）
-
-## 填写引导
-
-1. 遵循 `03-tdd.md` 的内置 TDD 指引，并先完成「执行前 Git 基线」检查。
-2. 在计划中记录当前分支、dirty/staged/untracked 摘要和 diff stat；已有改动默认视为用户工作，不能回退或覆盖。
-3. 按需读取同目录 `tests.md` / `mocking.md`，以及设计词汇单一事实源 `../../../vendor/codebase-design/`（`SKILL.md` 深模块与可测试接口设计、`DEEPENING.md` 依赖类别与接缝、`DESIGN-IT-TWICE.md` 备选接口）。
-4. 与用户确认公共接口、最重要的行为和测试覆盖优先级。
-5. 拆出第一个 tracing slice，避免水平切片。
-6. 探索代码库时使用项目领域术语表，确保测试名称和接口词汇与项目语言一致，并尊重触及区域的 ADR。
-7. 写任何代码前确认接口变更、优先测试的行为、deep module 机会、可测试接口设计和行为列表。
-8. **承载切片契约**：把本阶段对应切片的 **保留/不动** 与 **关键核实结论** 记入计划作为实现约束；切片行号为近似、以现场代码为准（现场核对）；存疑分支按 `../I-to-issues/issues-slices.md`「存疑时的提问协议」一次一问、带推荐、逐步锁定。
-
-## 边界
-
-- 本阶段不写代码。
-- 不批量预写所有测试。
-
-## 完成准则
-
-- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 slices 须与 `<phase>` 的 `id` 一致）
-- 已记录执行前 git 基线和未知/重叠改动处理结论
-- 多阶段：已记录本切片 **保留/不动** 约束与 **现场核对** 结论
-- `tdd-plan.md` 无残留 `[TODO:]`
-- `.status.json` 的 `implementation_status` 为 `planned`

package/template/workflows/dev/03-tdd/tests.md

@@ -1,61 +0,0 @@
-# 好测试与坏测试
-
-## 好测试
-
-**集成式**：通过真实接口测试，而不是 mock 内部组件。
-
-```typescript
-// 好：测试可观察的行为
-test("用户可以用有效购物车结算", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-特征：
-
-- 测试用户/调用者关心的行为
-- 只使用公共 API
-- 能经受住内部重构
-- 描述「做什么」，而不是「怎么做」
-- 每个测试一个逻辑断言
-
-## 坏测试
-
-**实现细节测试**：与内部结构耦合。
-
-```typescript
-// 坏：测试实现细节
-test("checkout 调用了 paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-危险信号：
-
-- mock 内部协作者
-- 测试私有方法
-- 断言调用次数/顺序
-- 重构时测试坏了但行为没变
-- 测试名称描述的是「怎么做」而不是「做什么」
-- 通过外部手段验证而不是通过接口
-
-```typescript
-// 坏：绕过接口来验证
-test("createUser 保存到数据库", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// 好：通过接口验证
-test("createUser 使用户可被检索", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```

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

@@ -1,57 +0,0 @@
----
-id: dev/finalize
-category: dev
-name: Finalize & Archive
-description: 在用证据证明 change 真正完成后，改变其状态并归档；没有新鲜验证证据不许宣称完成
-keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
----
-
-# Finalize & Archive 工作流执行指引
-
-本工作流是 `dev/04` 入口：先用证据证明"真的完成了"，再改变状态并归档。
-
-> **铁律：** 没有新鲜的验证证据，不许宣称完成。门控函数全文见 `completion-gate.md`。
-
-> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。归档目标为 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`。
-
-## 阶段
-
-| Phase | id | agent | 规范 | 模板 | 产物 |
-|-------|-----|-------|------|------|------|
-| 1. Completion Verification | `completion-verification` | `agents/completion-gate-agent.md` | `completion-gate.md` | `../_templates/completion-verification-template.md` | `completion-verification.md` |
-| 2. Merge Back & Cleanup | `merge-cleanup` | — | `../../../skills/worktree-isolation/SKILL.md` | — | 合并后的 base 分支 |
-| 3. Finalize & Archive | `finalize-archive` | — | `finalize-archive.md` | `../_templates/completion-summary-template.md` | `completion-summary.md` |
-
-### 1. Completion Verification — 完成前验证（门控）
-- id：`completion-verification`
-- 完成准则：每条结论有本次运行证据；`verification_status` 为 `verified` 或 `blocked`
-
-### 2. Merge Back & Cleanup — 合并回原分支（仅 worktree 模式）
-- id：`merge-cleanup`
-- 完成准则：非 worktree 模式标记 `skipped`；worktree 已合并并清理
-
-### 3. Finalize & Archive — 状态收尾与归档
-- id：`finalize-archive`
-- 完成准则：`change_status` 置 `completed` 并归档；已从 `dev-status.json` 移除
-
-## 依赖
-
-- 软依赖：`../03-tdd/03-tdd.md` 或 `../R-review/R-review.md`，scope: same-change
-- 硬依赖：无；但归档要求通过完成前验证
-
-## 状态扩展字段
-
-- `dev_entry` (string) — 固定为 `dev/04`
-- `verification_commands` (array)
-- `requirements_checklist` (array)
-- `verification_status` (verified | blocked)
-- `archived` (boolean)
-- `archive_path` (string|null)
-- `worktree_status` (created | active | merged | removed)
-
-## 完成与状态更新
-
-- `verification_status: blocked` 时停在本工作流，回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md`。
-- `verified` 且用户确认后：worktree 模式先 Phase 2，再置 `change_status: completed` → 归档 → `archived`。
-
-与 `../../../commands/archive.md` 的关系：本工作流面向单个 change 引导式收尾；archive 命令面向批量归档。

package/template/workflows/dev/04-finalize/agents/completion-gate-agent.md

@@ -1,35 +0,0 @@
----
-id: dev/04-finalize/completion-gate-agent
-type: agent
-name: Completion Gate Agent
-description: 隔离执行完成前验证门控，防自证完成
----
-
-## 使命
-
-独立验证 change 是否真正完成，产出 `completion-verification.md`，给出 `verified` 或 `blocked` 结论。
-
-## 输入契约
-
-- change 路径：`speculo/.speculo/dev/<change>/`
-- `current_phase` / phase-id：`completion-verification`
-- 上游产物：PRD / slices / 实现产物、`tdd/<phase-id>/verification.md`（若存在）
-- 模板：`../_templates/completion-verification-template.md`
-
-## 执行规范
-
-- 按 `../completion-gate.md` 执行门控函数：确定命令 → 运行 → 阅读输出 → 验证结论。
-- 每条完成结论必须有**本次运行**的命令与输出证据。
-- 对照来源逐项核对需求清单。
-- 产物写入 `speculo/.speculo/dev/<change>/completion-verification.md`。
-
-## 产物与状态
-
-- 产物：`completion-verification.md`
-- `.status.json`：写入 `verification_commands`、`requirements_checklist`、`verification_status`
-
-## 边界
-
-- 不越过本 phase；不执行归档或 worktree 合并。
-- 只有 `verified` 时主流程才可进入归档 phase；`blocked` 时停止。
-- 本 agent 可建议置 `change_status: completed`，但**只有主流程 `finalize-archive` phase** 实际写入。

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

@@ -1,41 +0,0 @@
-# Completion Verification Phase（门控）
-
-本阶段是归档前的门控。**没有本次运行的验证证据，不许进入下一阶段。**
-
-## 输入
-
-- 当前 change 目录：`speculo/.speculo/dev/<change>/` 下的实现产物（多阶段在 `tdd/<phase-id>/` 下的 `implementation-log.md`、`verification.md` 等）
-- 来源：PRD、issue、slices、诊断结论或用户明确任务
-- 项目的测试 / 类型检查 / lint / 构建命令
-- 变更 diff（VCS）
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/completion-verification.md`，由 `../_templates/completion-verification-template.md` 填写
-
-## 填写引导
-
-按 `04-finalize.md` 的门控函数，对每个完成结论"确定命令 → 运行 → 读输出 → 验证 → 才下结论"。
-
-1. **运行验证命令**：跑与变更相关的测试、类型检查、lint、构建。逐条记录**命令、退出码、通过/失败计数**。无法运行的命令记录原因，对应结论不得声称通过。
-2. **逐项核对需求**：重读来源（PRD / issue / slices / 用户任务），建立需求清单，逐项标 `satisfied | missing | partial` 并引用来源；测试通过不能替代需求核对。
-3. **回归证据**（若本 change 修了 bug）：确认回归测试经过红-绿验证（写 → 通过 → 回退修复必须失败 → 恢复 → 通过），而不是只通过一次。
-4. **代理产物核对**（若部分工作委派给子代理）：检查 VCS diff 验证实际变更，不信任代理的"成功"报告。
-5. **调试残留检查**：搜索临时日志、DEBUG 标记、一次性脚本、推测性 / 未启用功能并清理。
-6. **下结论**：全部结论均有新鲜证据支撑 → `verification_status: verified`；任一关键项缺证据或失败 → `verification_status: blocked`，并写明实际状态与缺口。
-
-## 边界
-
-- 不夸大、不用"应该""大概""似乎"等措辞；信心 ≠ 证据。
-- 不依赖上一轮的旧结果或部分检查。
-- `blocked` 时不进入归档；回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复后重跑本阶段。
-- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未授权的项目规则文档。
-
-## 完成准则
-
-- `completion-verification.md` 记录了每条结论的命令与输出证据
-- 需求清单逐项核对完成，含来源引用
-- 调试残留已清理或明确说明
-- `completion-verification.md` 无残留 `[TODO:]`
-- 多阶段 slices：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 slices 则不适用）
-- `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`