@namewta/speculo 0.1.19 → 0.1.21

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

@@ -8,151 +8,48 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 # TDD Implementation 工作流执行指引
 
-本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock 与重构指引内置在本 workflow 目录中；**深模块、接口、接缝、适配器的设计词汇与原则统一引用 `vendor/codebase-design`，本工作流不再复制**（见下「渐进披露」）。
+本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 细节见同目录 phase 文件；设计词汇统一引用 `../../../vendor/codebase-design/SKILL.md`。
 
-## 执行前 Git 基线
-
-开始 TDD 计划或写代码前，必须先查看当前目录所在仓库和分支的 git 情况：
-
-```bash
-git branch --show-current
-git status --short --branch
-git diff --stat
-git diff --cached --stat
-```
-
-- 把当前分支、dirty/staged/untracked 摘要记录到 `tdd/<phase-id>/tdd-plan.md`；进入实现循环后如状态变化，记录到 `implementation-log.md`。
-- 默认把已有改动视为用户或上一阶段留下的工作，不回退、不覆盖、不格式化无关文件。
-- 如果本阶段需要修改的文件已存在未知改动，先核对 diff；无法判断归属或改动会重叠时，停止并询问用户。
-- 若仓库不是 git 仓库或命令无法运行，记录失败原因和可见文件状态，再继续后续判断。
-
-## 内置指引
-
-### 核心原则
-
-测试应通过公共接口验证行为，而不是实现细节。代码可以完全重写；测试不应该。
-
-好的测试是集成式的：它们通过公共 API 运行真实的代码路径，描述系统“做什么”，不描述“怎么做”。坏的测试与实现耦合：mock 内部协作者、测试私有方法，或通过外部手段验证内部状态。
-
-### 反模式：水平切片
-
-不要先写全部测试，再写全部实现。正确做法是追踪弹式垂直切片：一个测试 -> 一个实现 -> 重复。每个测试都基于上一轮学到的东西做出响应。
-
-### 渐进披露
-
-测试与重构相关指引内置在同目录：
-
-- `tests.md`：设计测试方式（好测试 vs 坏测试）时读取。
-- `mocking.md`：考虑 mock 边界、为可 mock 性设计接口时读取。
-- `refactoring.md`：进入重构阶段、识别重构候选时读取。
-
-深模块 / 接口 / 接缝 / 适配器 / 杠杆 / 局部性的设计词汇与原则统一由 `vendor/codebase-design` 承载（**单一事实源，本工作流不复制**），按需直接引用：
-
-- `../../../vendor/codebase-design/SKILL.md`：设计深模块、判断深 vs 浅、为可测试性设计接口（接受依赖而非创建、返回结果而非副作用、小表面积）时读取——deep module 与可测试接口设计的权威来源。
-- `../../../vendor/codebase-design/DEEPENING.md`：判定依赖类别（进程内 / 本地可替换 / 端口与适配器 / mock）与「替换而非叠加」的测试策略时读取。
-- `../../../vendor/codebase-design/DESIGN-IT-TWICE.md`：需要为深化候选并行探索多个备选接口时读取。
-
-### 消费 slices 切片契约
-
-多阶段 change 从 `slices.md` 接手时，每个 TDD 阶段对应一个切片，须读取并守护该切片契约（见 `../I-to-issues/issues-slices.md`）：
-
-- **保留/不动**：把切片的「保留/不动」清单当作实现硬约束——冻结常量 / 共享依赖 / 邻近功能一律不碰。
-- **关键核实结论与行号现场核对**：切片记录的行号为*近似*，实现时一律以现场代码为准、不照搬。
-- **验收切片**：Finish 阶段运行切片的「验收切片」；删除型切片须含残留扫描（`grep` 0 命中）并留证。
-- **横切铁律**：遵守 §4 横切关注点（契约先行、删缓存可重建、数据安全冻结等）。
-- **存疑即问**：计划阶段遇未决分支，按 `../I-to-issues/issues-slices.md`「存疑时的提问协议」一次一问、带推荐、逐步锁定。
+> **产物目录：** `speculo/.speculo/dev/<change>/tdd/<phase-id>/`。`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。
 
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `speculo/.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-user-auth`）。
+| 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 — 行为与接口计划
-- 规范：`tdd-plan.md`
-- 模板：`../_templates/tdd-plan-template.md`
-- 产物：`tdd/<phase-id>/tdd-plan.md`
-- 完成准则：
-  - 已确认公共接口、关键行为和测试优先级
-  - 已在产物顶部「阶段标识」段填写 `<phase-id>`
-  - `tdd-plan.md` 无残留 `[TODO:]`
+- id：`tdd-plan`
+- 完成准则：公共接口与测试优先级已确认；`tdd-plan.md` 无残留 `[TODO:]`
 
 ### 2. Slice Loop — 红绿重构循环
-- 规范：`tdd-loop.md`
-- 模板：`../_templates/tdd-log-template.md`
-- 产物：`tdd/<phase-id>/implementation-log.md`
-- 完成准则：
-  - 每个切片都有 RED、GREEN、REFACTOR 和验证记录
-  - `implementation-log.md` 无残留 `[TODO:]`
+- id：`slice-loop`
+- 完成准则：每切片有 RED/GREEN/REFACTOR 记录；`implementation-log.md` 无残留 `[TODO:]`
 
 ### 3. Finish — 验证与收尾
-- 规范：`tdd-finish.md`
-- 模板：`../_templates/tdd-verification-template.md`
-- 产物：`tdd/<phase-id>/verification.md`
-- 完成准则：
-  - 已运行相关测试或明确记录无法运行原因
-  - 无调试残留和推测性功能
-  - 已把 slices 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 slices 则跳过，见「phase 阶段状态（XML 契约）」）
-  - `verification.md` 无残留 `[TODO:]`
-
-## TDD 产物目录与阶段标识
-
-- 本工作流所有产物集中在 `speculo/.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
-- `<change>` 为当前 change 目录名（`YYYY-MM-DD-<kebab-name>`）。
-- `<phase-id>` 标识：
-  - 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>`。
-- 目录形如：
+- id：`tdd-finish`
+- 完成准则：验证已运行；slices 状态已翻转（若有）；`verification.md` 无残留 `[TODO:]`
 
-```text
-speculo/.speculo/dev/<change>/tdd/
-├── phase0-node-base/
-│   ├── tdd-plan.md
-│   ├── implementation-log.md
-│   └── verification.md
-└── phase1-templates/
-    ├── tdd-plan.md
-    ├── implementation-log.md
-    └── verification.md
-```
-
-## phase 阶段状态（XML 契约）
-
-多阶段 change（`speculo/.speculo/dev/<change>/slices.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
-
-```xml
-<phase id="phase0-node-base" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
-```
-
-- `id`：阶段稳定标识，与 TDD 产物目录 `tdd/<phase-id>/` 同名。
-- `status` 枚举与责任方：
-  - `未开始` —— 创建 slices 文档时由作者初始化（所有阶段默认 `未开始`）。
-  - `已实现` —— 本工作流（`dev/03`）该阶段 Finish 验证通过后置入。
-  - `已验证` —— `dev/04`（`../04-finalize/04-finalize.md`）完成前验证通过后置入。
-- 本工作流只负责 `未开始 → 已实现` 这一跳；`dev/04` 负责 `已实现 → 已验证`。状态只前进不回退，除非该阶段被显式重做。
-- change 无 slices（单阶段直接任务）时本契约不适用，跳过状态翻转。
+slices 消费契约、Git 基线、XML 阶段状态见 `tdd-plan.md` 与 `tdd-finish.md`。
 
 ## 依赖
 
 - 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
-- 硬依赖：无；若用户提供明确修复或实现任务，可直接进入
+- 硬依赖：无
 
 ## 状态扩展字段
 
-本工作流需在同 change 的 `.status.json` 追加：
-
 - `dev_entry` (string) — 固定为 `dev/03`
-- `embedded_guides` (array) — 包含 `tdd`
-- `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) — 已运行或应运行的验证命令
-- `implementation_status` (planned | in-progress | verified | blocked) — 实现状态
-
-> 多阶段 change：上述自治字段按阶段命名空间记录在 `tdd_runs[<phase-id>]` 下（各含 `scope` / `artifacts`(指向 `tdd/<phase-id>/*.md`) / `red_green_refactor_cycles` / `verification_commands` / `implementation_status`），避免跨阶段互相覆盖。单阶段 change 可直接用平铺字段。
+- `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`。
-- 每完成一个切片，追加 `red_green_refactor_cycles`（多阶段时写入 `tdd_runs[<phase-id>]`）。
-- Finish 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 slices 则跳过）。
-- 全部用户要求的实现边界完成并验证后，可把 `change_status` 置为 `completed`，或移交 review/handoff command。
+- 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

@@ -0,0 +1,34 @@
+---
+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

@@ -0,0 +1,34 @@
+---
+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

@@ -0,0 +1,34 @@
+---
+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/04-finalize/04-finalize.md

@@ -8,130 +8,50 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 
 # Finalize & Archive 工作流执行指引
 
-本工作流是 `dev/04` 入口，是开发主线的收尾环节（`dev/01` → `dev/02` → `dev/I` → `dev/03` → `dev/04`）。它在 change 的实现完成后，**先用证据证明"真的完成了"，再改变状态并归档**。
+本工作流是 `dev/04` 入口：先用证据证明"真的完成了"，再改变状态并归档。
 
-> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。归档目标为 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
+> **铁律：** 没有新鲜的验证证据，不许宣称完成。门控函数全文见 `completion-gate.md`。
 
-## 内置指引
-
-### 核心原则
-
-> 在没有验证的情况下宣称工作完成，这不是高效，而是不诚实。**始终用证据支撑结论。**
-
-### 铁律
-
-```
-没有新鲜的验证证据，不许宣称完成
-```
-
-如果你在本次推进中没有运行验证命令，就不能声称测试通过、构建成功或需求满足。对这条规则敷衍了事，就等于违背了它的精神。
-
-### 门控函数
-
-在把 change 标记为 completed 之前，对每个结论执行：
-
-```
-1. 确定：什么命令能证明这个结论？
-2. 运行：执行完整命令（重新运行，完整执行）
-3. 阅读：完整输出，检查退出码，统计失败数
-4. 验证：输出是否支持这个结论？
-   - 否 → 用证据说明实际状态，置 blocked
-   - 是 → 带证据陈述结论
-5. 只有这时：才能做出结论
-跳过任何一步 = 说谎，不是验证
-```
-
-### 常见失败模式
-
-| 结论 | 需要 | 不够格 |
-|------|------|--------|
-| 测试通过 | 测试命令输出：0 failures | 之前的运行、"应该会通过" |
-| Linter 无报错 | Linter 输出：0 errors | 部分检查、推断 |
-| 构建成功 | 构建命令：exit 0 | linter 通过、日志看起来没问题 |
-| Bug 已修复 | 测试原始症状：通过 | 代码改了，假设已修复 |
-| 回归有效 | 红-绿循环已验证 | 测试只通过了一次 |
-| 代理已完成 | VCS diff 显示变更 | 代理报告"成功" |
-| 需求已满足 | 逐项核对清单 | 测试通过 |
-
-### 红线 —— 停下来
-
-出现以下任一情况，**不得进入归档**，回到验证：
-
-- 使用"应该""大概""似乎"
-- 验证前就表达满意（"太好了""完美""搞定"）
-- 即将归档却没有新鲜验证
-- 信任代理的成功报告而未独立核对 VCS diff
-- 依赖部分验证或上一轮的旧结果
-
-### 何时使用
-
-当一个 change 的实现（`dev/03` 或 hotfix 修复）已结束，用户要把它**收尾、标记完成并归档**时使用。也可在 `dev/R` 审查通过后衔接进入。
-
-### 与 `archive` 命令的关系
-
-- 本工作流（`dev/04`）面向**单个当前 change** 的引导式收尾：先验证、改状态、再归档。
-- `../../../commands/archive.md` 面向**批量**归档多个已 `completed` 的 change。两者共用同一套破坏性归档安全契约（先列清单、用户确认、不覆盖）。
+> **目录命名：** `<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 — 完成前验证（门控）
-- 规范：`completion-gate.md`
-- 模板：`../_templates/completion-verification-template.md`
-- 产物：`completion-verification.md`
-- 完成准则：
-  - 每条完成结论都有**本次运行**的命令与输出证据
-  - 已对照来源（PRD / issue / slices / 用户任务）逐项核对需求清单
-  - 无调试残留与推测性功能
-  - （如适用）实现期引入的新领域术语 / 架构决策已按 `../M-domain-modeling/M-domain-modeling.md` 沉淀到 CONTEXT / ADR（模型未漂移）；无新术语则不适用
-  - `completion-verification.md` 无残留 `[TODO:]`
-  - `.status.json` 的 `verification_status` 为 `verified` 或 `blocked`
-
-### 2. Merge Back & Cleanup — 合并回原分支与清理（条件，仅 worktree 模式）
-- 规范：`../../../skills/worktree-isolation/SKILL.md`（读其 `references/merge-and-cleanup.md`）
-- 模板：无
-- 产物：合并后的 base 分支、移除的 `.worktree/<change>/` 工作树与隔离分支
-- 完成准则：
-  - 非 worktree 模式本 phase 标记 `skipped`，不读取该 skill
-  - `verification_status: verified` 且用户确认后才执行（破坏性）
-  - change 分支已合并回 `base_branch`（冲突即停、不强推），置 `worktree_status: merged`
-  - `.worktree/<change>/` 工作树与隔离分支已清理，置 `worktree_status: removed`
+- id：`completion-verification`
+- 完成准则：每条结论有本次运行证据；`verification_status` 为 `verified` 或 `blocked`
+
+### 2. Merge Back & Cleanup — 合并回原分支（仅 worktree 模式）
+- id：`merge-cleanup`
+- 完成准则：非 worktree 模式标记 `skipped`；worktree 已合并并清理
 
 ### 3. Finalize & Archive — 状态收尾与归档
-- 规范：`finalize-archive.md`
-- 模板：`../_templates/completion-summary-template.md`
-- 产物：`completion-summary.md`，以及归档动作
-- 完成准则：
-  - `verification_status` 为 `verified`（`blocked` 时不得归档）
-  - worktree 模式下，归档在 `base_branch` 上进行（change 目录已随 Phase 2 合并到达 base）
-  - `change_status` 先置 `completed`，再随归档置 `archived`
-  - change 目录已移动到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
-  - 已从 `speculo/.speculo/dev-status.json` 的 `active[]` 移除该 change
-  - `completion-summary.md` 无残留 `[TODO:]`
+- id：`finalize-archive`
+- 完成准则：`change_status` 置 `completed` 并归档；已从 `dev-status.json` 移除
 
 ## 依赖
 
 - 软依赖：`../03-tdd/03-tdd.md` 或 `../R-review/R-review.md`，scope: same-change
-- 硬依赖：无；但归档要求当前 change 通过完成前验证
+- 硬依赖：无；但归档要求通过完成前验证
 
 ## 状态扩展字段
 
-本工作流需在同 change 的 `.status.json` 追加：
-
 - `dev_entry` (string) — 固定为 `dev/04`
-- `verification_commands` (array) — 本次运行的验证命令及结果摘要
-- `requirements_checklist` (array) — 逐项需求核对结果，每项含来源引用与 satisfied | missing | partial
-- `verification_status` (verified | blocked) — 完成前验证结论
-- `archived` (boolean) — 是否已完成归档
-- `archive_path` (string|null) — 归档目标路径
-- `worktree_status` (created | active | merged | removed) — 仅 worktree 模式；本工作流在 Phase 2 推进到 `merged` → `removed`（字段定义见 `../../../skills/worktree-isolation/SKILL.md`）
+- `verification_commands` (array)
+- `requirements_checklist` (array)
+- `verification_status` (verified | blocked)
+- `archived` (boolean)
+- `archive_path` (string|null)
+- `worktree_status` (created | active | merged | removed)
 
 ## 完成与状态更新
 
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 完成验证后写入 `verification_commands`、`requirements_checklist`、`verification_status`。
-- 多阶段 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。
-  - 置 `change_status: completed` → 执行归档 → 置 `change_status: archived`、`archived: true`、写 `archive_path`，并从 `speculo/.speculo/dev-status.json` 移除。
-- 如有可沉淀经验，在用户或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
+- `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

@@ -0,0 +1,35 @@
+---
+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/A-improve-architecture/A-improve-architecture.md

@@ -8,136 +8,53 @@ keywords: [architecture, deepening, deep-module, refactor, 架构, 深化, 接
 
 # Improve Architecture 工作流执行指引
 
-本工作流是 `dev/A` 入口：浮现架构摩擦、提出**深化机会**（把浅模块转化为深模块的重构），目标是可测试性与 AI 可导航性。它**建立在共享设计词汇与项目领域模型之上**：
+本工作流是 `dev/A` 入口：浮现架构摩擦、提出**深化机会**，目标是可测试性与 AI 可导航性。架构词汇统一引用 `../../../vendor/codebase-design/SKILL.md`；领域语言以 `speculo/.speculo/.config/context/CONTEXT.md` 为准。
 
-- 架构词汇与原则（模块 / 接口 / 深度 / 接缝 / 适配器 / 杠杆 / 局部性；删除测试、「接口就是测试表面」、「一个适配器 = 假设接缝，两个 = 真实接缝」）统一引用 `../../../vendor/codebase-design/SKILL.md`（及 `DEEPENING.md`）。在每条建议中**严格使用**这些术语——不要偏离到「组件 / 服务 / API / 边界」。
-- 领域语言来自 `speculo/.speculo/.config/context/CONTEXT.md`（为好接缝命名）；`speculo/.speculo/.config/adr/` 中的 ADR 记录本工作流**不应重新争议**的决策。领域模型的主动维护见 `../M-domain-modeling/M-domain-modeling.md`。
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`。产物写入 `speculo/.speculo/dev/<change>/`。
 
-## 内置指引
+## 何时使用
 
-### 何时使用
-
-当用户想系统性发现并落实架构深化机会（让代码更可测试、对 AI 更可导航）时使用。也可由 `../H-diagnose/H-diagnose.md` 在修复后转入——当 Bug 根因涉及架构（没有好接缝、纠缠调用者、隐藏耦合）时。
-
-### 输入
-
-- 当前 git 仓库与待改进的代码区域
-- `speculo/.speculo/.config/context/CONTEXT.md` 领域词汇、触及区域的 `speculo/.speculo/.config/adr/` ADR
-- 设计词汇单一事实源 `../../../vendor/codebase-design/SKILL.md`、`DEEPENING.md`、`DESIGN-IT-TWICE.md`
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-deepen-order-intake`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/architecture-candidates.md` —— 结构化深化候选清单
-- `speculo/.speculo/dev/<change>/architecture-review.html` —— 可视化架构审查报告（前后对比图 + 推荐强度）
-- `speculo/.speculo/dev/<change>/architecture-design.md` —— 选中候选经质询后的接口设计与决策
-- 经用户确认后更新 `.config/context/`、`.config/adr/`（经 `../M-domain-modeling/`）
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 核心原则（引用 codebase-design）
-
-- **删除测试**：对任何疑似浅的模块，想象删除它——复杂性会集中（好信号，值得深化）还是只是移动？
-- **深度是接口的属性**：小接口 + 大量实现；深化 = 缩小接口、把复杂性吸收进实现。
-- **接缝纪律**：一个适配器 = 假设接缝，两个 = 真实接缝；不要为单一实现凭空切接缝。
-- 完整原则、依赖类别与「替换而非叠加」测试策略见 `../../../vendor/codebase-design/SKILL.md` 与 `DEEPENING.md`，本工作流不复制。
-
-### 渐进披露
-
-- `HTML-REPORT.md`：编写 `architecture-review.html` 时读取——完整 HTML 框架、图表模式与样式指南。
-
-### 独立使用
-
-本工作流**零硬依赖**，无需预先执行其他工作流即可独立进入（`dev/A`）。只需当前 git 仓库即可启动；缺 change 目录时按下「自初始化」创建；缺 CONTEXT / ADR 时按代码现状探索，不阻塞。
-
-### 缺少 change 目录时的自初始化
-
-若当前无对应 change 目录：
-
-1. 从用户意图提取 `<kebab-name>`（如 `deepen-order-intake`）
-2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
-3. 初始化 `.status.json`：
-   ```json
-   {
-     "dev_entry": "dev/A",
-     "current_phase": "1. Scan",
-     "phase_history": [],
-     "change_status": "active",
-     "embedded_guides": ["improve-architecture"],
-     "candidate_count": 0,
-     "selected_candidate": null,
-     "report_path": null,
-     "architecture_status": "scanning"
-   }
-   ```
-4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组追加该 change 目录名
+当用户想系统性发现并落实架构深化机会时使用。也可由 `../H-diagnose/H-diagnose.md` 在修复后转入。
 
 ## 阶段
 
-> **持久化铁律**：所有产物（含 HTML 报告）写入 `speculo/.speculo/dev/<change>/`，**禁止写入 `temp/`、系统临时目录或项目根目录**。
+| Phase | id | 规范 | 产物 |
+|-------|-----|------|------|
+| 1. Scan | `architecture-scan` | `architecture-scan.md` | `architecture-candidates.md` |
+| 2. Report | `architecture-review` | `architecture-review.md`、`HTML-REPORT.md` | `architecture-review.html` |
+| 3. Grill | `architecture-grill` | `architecture-grill.md` | `architecture-design.md` |
 
 ### 1. Scan — 探索深化候选
-- 规范：本入口「核心原则」+ `../../../vendor/codebase-design/SKILL.md`、`../../../vendor/codebase-design/DEEPENING.md`
-- 模板：无（候选条目结构见下「引导」第 4 步）
-- 产物：`architecture-candidates.md`
-- 引导：
-  1. 先读 `speculo/.speculo/.config/context/CONTEXT.md` 与触及区域的 `.config/adr/`。
-  2. 用 Agent 工具（`subagent_type=Explore`）有机地遍历代码库，注意摩擦：理解一个概念要在许多小模块间跳转？模块浅（接口几乎和实现一样复杂）？纯函数仅为可测试性而提取、真 bug 藏在其调用方式里（没有局部性）？紧耦合模块在接缝处泄漏？哪些区域难以通过当前接口测试？
-  3. 对每个疑似浅模块应用**删除测试**，保留「删除会集中复杂性」的候选。
-  4. 每个候选记录：**涉及文件**、**问题**（当前摩擦）、**解决方案**（通俗语言）、**收益**（用局部性 / 杠杆 / 测试改善表述）、**依赖类别**（进程内 / 本地可替换 / 端口与适配器 / mock）、**推荐强度**（强烈 / 值得探索 / 推测性）。
-  5. 与现有 ADR 冲突的候选，仅在摩擦真实到值得重审 ADR 时保留，并在条目中显式标注（如「与 ADR-0007 矛盾——但因……值得重新讨论」）。
-- 完成准则：
-  - 候选均用 codebase-design 词汇命名（不散用「组件 / 服务 / 边界」）
-  - 每个候选含文件、问题、解决方案、收益、依赖类别、推荐强度
-  - `architecture-candidates.md` 无残留 `[TODO:]`
+- id：`architecture-scan`
+- 完成准则：`architecture-candidates.md` 无残留 `[TODO:]`；候选用 codebase-design 词汇命名
 
 ### 2. Report — 可视化架构审查报告
-- 规范：`HTML-REPORT.md`
-- 模板：无
-- 产物：`architecture-review.html`
-- 引导：
-  1. 按 `HTML-REPORT.md` 编写**自包含** HTML（Tailwind + Mermaid 走 CDN），每个候选一张卡片含**前后对比图**，结尾「首要推荐」段。
-  2. 写入 `speculo/.speculo/dev/<change>/architecture-review.html`（**不写临时目录**），用 OS 命令打开（macOS `open <path>`、Linux `xdg-open <path>`、Windows `start <path>`），并告知用户绝对路径。
-  3. 领域用 CONTEXT 词汇、架构用 codebase-design 词汇。
-  4. 此时不提接口设计；写入并打开后，询问用户：「这些候选你想探索哪一个？」
-- 完成准则：
-  - HTML 自包含、每个候选有前后对比图与推荐强度徽章、含首要推荐段
-  - 报告写入 change 目录并已为用户打开
-  - 已请用户选择候选
+- id：`architecture-review`
+- 完成准则：HTML 已写入 change 目录并为用户打开；已请用户选择候选
 
 ### 3. Grill — 质询所选候选并沉淀
-- 规范：`../../../skills/grill-me/SKILL.md`（逐问压测）+ `../M-domain-modeling/M-domain-modeling.md`（内联沉淀）
-- 模板：无
-- 产物：`architecture-design.md`；经用户确认后更新 `.config/context/`、`.config/adr/`
-- 引导：
-  1. 用 `../../../skills/grill-me/SKILL.md` 与用户走设计树：约束、依赖、深化后模块形态、接缝后面是什么、哪些测试存活。
-  2. 决策结晶时按 `../M-domain-modeling/M-domain-modeling.md` 内联沉淀：深化模块用了 CONTEXT 没有的概念 → 加术语；锐化了模糊术语 → 更新 CONTEXT；用户以关键理由否决候选 → 按 ADR 三判据决定是否记 ADR（防止未来架构审查重复建议同一件事）。
-  3. 想探索深化模块的备选接口时，按 `../../../vendor/codebase-design/DESIGN-IT-TWICE.md` 的「设计两次」并行子代理模式。
-- 完成准则：
-  - 选中候选的接口、依赖策略与适配器、存活测试已记入 `architecture-design.md`
-  - 决策结晶处的术语 / ADR 已按 `../M-domain-modeling/` 沉淀（经用户确认）
-  - `architecture-design.md` 无残留 `[TODO:]`
+- id：`architecture-grill`
+- 完成准则：`architecture-design.md` 无残留 `[TODO:]`；术语/ADR 经用户确认后沉淀
 
 ## 依赖
 
-- 硬依赖：无（零依赖横向工作流）
-- 软依赖：无。可独立进入；也可由 `../H-diagnose/H-diagnose.md` 修复后转入。建立在 `../../../vendor/codebase-design/`（设计词汇）与 `../M-domain-modeling/`（领域模型）之上；深化的实现落地交由 `../03-tdd/03-tdd.md`。
+- 硬依赖：无
+- 软依赖：`../M-domain-modeling/`（领域沉淀）、`../03-tdd/03-tdd.md`（实现落地）
 
 ## 状态扩展字段
 
-本工作流需在同 change 的 `.status.json` 追加：
-
 - `dev_entry` (string) — 固定为 `dev/A`
 - `embedded_guides` (array) — 包含 `improve-architecture`
-- `candidate_count` (number) — 深化候选数量
-- `selected_candidate` (string|null) — 用户选中的候选
-- `report_path` (string|null) — `speculo/.speculo/dev/<change>/architecture-review.html`
-- `architecture_status` (scanning | reported | grilling | designed | blocked) — 工作流状态
+- `candidate_count` (number)
+- `selected_candidate` (string|null)
+- `report_path` (string|null)
+- `architecture_status` (scanning | reported | grilling | designed | blocked)
 
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 报告生成后写入 `candidate_count`、`report_path`，置 `architecture_status: reported`。
-- 用户选定并质询后写入 `selected_candidate`，置 `architecture_status: designed`。
-- 写 `.config/context/` 或 `.config/adr/` 前必须经用户确认（经 `../M-domain-modeling/`）。
 - 本工作流不自动完成 change；深化的实现交由 `../03-tdd/03-tdd.md` 落地。
+
+### 缺少 change 目录时
+
+若无 active change，执行 `../AGENTS.md` 进入协议步骤 3（原子三步），不得内联自初始化 JSON。