@namewta/speculo 0.1.20 → 0.2.0

package/template/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -1,107 +0,0 @@
----
-id: dev/grill-with-docs
-category: dev
-name: Grill With Docs
-description: 结合项目术语、CONTEXT 与 ADR 对方案进行领域澄清和决策压力测试
-keywords: [grill, context, adr, 术语, 决策]
----
-
-# Grill With Docs 工作流执行指引
-
-本工作流用于在 PRD 或实现前澄清领域语言、识别决策分支，并把已确认的上下文沉淀为当前 change 的可追踪产物。**领域建模的主动纪律（挑战术语、锐化语言、压测边界）与 CONTEXT / ADR 格式由横向工作流 `../M-domain-modeling/M-domain-modeling.md` 拥有**，本工作流引用之，专注把拷问结论落到当前 change 的 `context-map.md` 与 `decision-log.md`。
-
-## 内置指引
-
-### 何时使用
-
-当 dev workflow 需要把用户方案与现有领域模型、术语表、ADR 或代码现实交叉验证时使用。
-
-### 输入
-
-- 用户提出的计划、需求、设计或变更意图
-- `speculo/.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
-- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md`、`speculo/.speculo/.config/adr/` 和相关代码
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/context-map.md`
-- `speculo/.speculo/dev/<change>/decision-log.md`
-- 已确认的术语、决策、开放问题和 ADR 候选
-- 需要用户进一步决策的问题，每次只问一个
-
-（`<change>` 为当前 change 目录名，格式 `YYYY-MM-DD-<kebab-name>`）
-
-### 执行原则
-
-针对计划的每个方面不断向用户提问，直到达成共识。沿着设计树的每条分支逐一展开，逐个解决决策之间的依赖关系。对于每个问题，给出推荐答案。
-
-每次只问一个问题，等待用户对当前问题的反馈后再继续。如果某个问题可以通过探索代码库来回答，就直接探索代码库。
-
-需要格式约定时读取 `../M-domain-modeling/CONTEXT-FORMAT.md` 或 `../M-domain-modeling/ADR-FORMAT.md`（格式单一事实源）；主动拷问的具体手法见 `../M-domain-modeling/M-domain-modeling.md`「会话期间（主动纪律）」。项目 CONTEXT 或 ADR 的创建、修改必须写入 `speculo/.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
-
-### Worktree 隔离（条件）
-
-**默认不启用。** 仅当用户**显式请求**把本 change 隔离推进（“用 worktree / 隔离这个 change / 不污染当前分支”）时，才进入下方 Phase 0，并读取 `../../../skills/worktree-isolation/SKILL.md` 的「创建」渐进披露执行隔离。
-
-- 用户未请求隔离时，**不读取**该 skill，跳过 Phase 0，按既有流程在当前分支推进，行为零变化。
-- 启用后，本 change 的代码与全部 Speculo 产物都落在隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树内，原分支不被污染；状态里记录 `base_branch` 与 `change_branch`，供 review、finalize 跨阶段跟进。
-- 隔离前置不满足（非 git 仓库 / 工作区不净 / `speculo/.speculo/` 未被 git 跟踪）时由该 skill 降级为非 worktree 模式并报告，不强行创建。
-
-## 阶段
-
-### 0. Worktree Setup — 隔离环境建立（条件，仅 worktree 模式）
-- 规范：`../../../skills/worktree-isolation/SKILL.md`（读其 `references/create-worktree.md`）
-- 模板：无
-- 产物：隔离分支 `speculo/dev/<change>`、`.worktree/<change>/` 工作树，以及 `.status.json` 的 worktree 字段
-- 完成准则：
-  - 用户未请求隔离时本 phase 标记 `skipped`，不读取该 skill
-  - 启用时分支与工作树已创建，且后续工作均切入 `.worktree/<change>/`
-  - `.status.json` 写入 `worktree_enabled`、`base_branch`、`change_branch`、`worktree_path`，`worktree_status: active`
-
-### 1. Context Scan — 上下文扫描
-- 规范：`grill-context-scan.md`
-- 模板：`../_templates/grill-context-map-template.md`
-- 产物：`context-map.md`
-- 完成准则：
-  - 已记录相关术语表、ADR、代码区域和缺口
-  - `context-map.md` 无残留 `[TODO:]`
-
-### 2. Decision Grill — 决策拷问
-- 规范：`grill-decision.md`
-- 模板：`../_templates/grill-decision-log-template.md`
-- 产物：`decision-log.md`
-- 完成准则：
-  - 关键决策均有结论、推荐答案或开放问题
-  - 需要写入 `speculo/.speculo/.config/context/` 或 `speculo/.speculo/.config/adr/` 的内容已获用户确认，或记录为候选
-  - `decision-log.md` 无残留 `[TODO:]`
-
-## 依赖
-
-- 软依赖：无
-- 硬依赖：无
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/01`
-- `embedded_guides` (array) — 包含 `grill-with-docs`
-- `context_paths` (array) — 已读取的 CONTEXT、ADR、代码或配置路径
-- `decision_status` (open | resolved | blocked) — 决策澄清状态
-- `adr_candidates` (array) — ADR 候选清单
-
-仅当用户请求 worktree 隔离（Phase 0）时追加，字段定义见 `../../../skills/worktree-isolation/SKILL.md` 的输出契约：
-
-- `worktree_enabled` (bool) — 是否启用隔离
-- `base_branch` (string) — 原分支
-- `change_branch` (string) — 隔离分支 `speculo/dev/<change>`
-- `worktree_path` (string) — `.worktree/<change>`
-- `worktree_status` (created | active | merged | removed) — 隔离生命周期状态，本 workflow 写到 `active`
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- phase 完成后更新 `updated_at`、产物路径和扩展字段。
-- 启用 worktree 隔离时，Phase 0 完成后写入 worktree 字段并置 `worktree_status: active`；未启用时 Phase 0 记 `skipped`，不写 worktree 字段。
-- 本 workflow 完成后不自动完成 change；默认移交 `../02-prd/02-prd.md` 或按用户要求停止。

package/template/workflows/dev/01-grill-with-docs/grill-context-scan.md

@@ -1,30 +0,0 @@
-# Context Scan Phase
-
-## 输入
-
-- 用户提出的计划、需求、设计或问题
-- `speculo/.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
-- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md`、`speculo/.speculo/.config/adr/` 和相关代码
-- 本 workflow 入口文件中的内置领域拷问指引
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/context-map.md`，由 `../_templates/grill-context-map-template.md` 填写
-
-## 填写引导
-
-1. 先探索仓库事实，不向用户询问可从文件中确认的问题。
-2. 记录存在的领域术语来源、ADR 来源、关键模块和调用者。
-3. 标出缺失的术语表、缺失 ADR 或与用户描述冲突的代码事实。
-4. 只记录事实和待确认项，不在本阶段做方案裁决。
-5. 若 `speculo/.speculo/.config/context/CONTEXT-MAP.md` 存在，先读取它以判断涉及哪个上下文；若只有 `speculo/.speculo/.config/context/CONTEXT.md`，按单上下文处理；若都不存在，只记录“缺少术语表”，不在本阶段创建。
-
-## 边界
-
-- 不直接修改 `speculo/.speculo/.config/context/` 或 `speculo/.speculo/.config/adr/`；修改动作留到 Decision Grill 阶段确认后执行。
-- 不创建实现计划或 PRD。
-
-## 完成准则
-
-- `context-map.md` 无残留 `[TODO:]`
-- 已列出下一阶段必须追问的最高优先级问题

package/template/workflows/dev/01-grill-with-docs/grill-decision.md

@@ -1,38 +0,0 @@
-# Decision Grill Phase
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/context-map.md`
-- 用户当前方案或目标
-- 本 workflow 入口文件中的内置领域拷问指引
-- `../M-domain-modeling/CONTEXT-FORMAT.md`、`../M-domain-modeling/ADR-FORMAT.md`（格式单一事实源）；主动拷问手法见 `../M-domain-modeling/M-domain-modeling.md`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/decision-log.md`，由 `../_templates/grill-decision-log-template.md` 填写
-- 可选：经用户确认后更新 `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md` 或 `speculo/.speculo/.config/adr/*.md`
-
-## 填写引导
-
-1. 遵循 `01-grill-with-docs.md` 的内置指引，再按需读取 `../M-domain-modeling/` 的格式文档与主动拷问纪律。
-2. 每次只问一个会改变决策树的问题，并给出推荐答案。
-3. 对术语冲突、代码现实冲突和 ADR 候选直接指出。
-4. 用户确认后，把决策写入 `decision-log.md`。
-5. 只有用户明确同意时，才把术语写入 `speculo/.speculo/.config/context/` 或创建 `speculo/.speculo/.config/adr/` 下的 ADR。
-6. 当用户使用的术语与 `speculo/.speculo/.config/context/` 中已有定义冲突时，立即指出冲突并要求在当前问题中消解。
-7. 当用户使用含混或一词多义的术语时，提议一个精确的规范术语。
-8. 当讨论领域关系时，用具体场景压力测试边界情况。
-9. 当用户描述某个东西如何运作时，检查代码是否一致；若矛盾，直接指出。
-10. 只有同时满足“难以逆转”“缺少上下文会令人意外”“真实权衡的结果”三个条件时，才提议 ADR。
-
-## 边界
-
-- 不输出 PRD；PRD 由 `../02-prd/02-prd.md` 负责。
-- 不把未确认的 ADR 候选写成正式 ADR。
-- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
-
-## 完成准则
-
-- 每个关键问题都有结论、推荐答案或 blocked 原因
-- `.status.json` 的 `decision_status` 已更新
-- `decision-log.md` 无残留 `[TODO:]`

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/prd-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/prd-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,158 +0,0 @@
----
-id: dev/tdd
-category: dev
-name: TDD Implementation
-description: 按垂直切片执行红绿重构，实现功能或回归修复
-keywords: [tdd, implement, red-green-refactor, 实现, 测试]
----
-
-# TDD Implementation 工作流执行指引
-
-本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock 与重构指引内置在本 workflow 目录中；**深模块、接口、接缝、适配器的设计词汇与原则统一引用 `vendor/codebase-design`，本工作流不再复制**（见下「渐进披露」）。
-
-## 执行前 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>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-user-auth`）。
-
-### 1. TDD Plan — 行为与接口计划
-- 规范：`tdd-plan.md`
-- 模板：`../_templates/tdd-plan-template.md`
-- 产物：`tdd/<phase-id>/tdd-plan.md`
-- 完成准则：
-  - 已确认公共接口、关键行为和测试优先级
-  - 已在产物顶部「阶段标识」段填写 `<phase-id>`
-  - `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:]`
-
-### 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>`。
-- 目录形如：
-
-```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（单阶段直接任务）时本契约不适用，跳过状态翻转。
-
-## 依赖
-
-- 软依赖：`../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 可直接用平铺字段。
-
-## 完成与状态更新
-
-- 进入每个 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。

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`