specwf 0.2.2 → 0.3.0

package/dist/templates/artifacts/state.md

@@ -1,158 +0,0 @@
----
-# ============================================================
-# specwf 状态机 frontmatter
-# ============================================================
-# 注意：这是 YAML frontmatter，缩进和空格敏感。
-# 不要使用 Tab，不要混用空格缩进层级。
-
-# 项目元信息
-project:
-  name: {{name}}           # 项目名，与 project.yml 一致
-  status: initialized       # 项目级状态机当前步
-                            #   initialized → requirements-defined → researched → roadmap-defined
-                            #   → milestone-active → project-done / project-paused / project-aborted
-  current_milestone: null   # 当前活跃 Milestone 名称，如 milestone-1, v2-migration
-  current_phase: null       # 当前活跃 Phase 名称
-                            #   如: auth-system, data-migration
-
-# 当前活跃上下文（项目层或某个实体层）
-active_context:
-  type: project             # 当前上下文类型: project / milestone / phase / change / adhoc
-  ref: null                 # 当前上下文的引用名称（如 phase 名称或 change ID）
-  step: init                # 当前上下文所在的步骤名
-                            #   项目层步: init, requirements, research, roadmap
-                            #   Phase 层步: discuss, research, split, apply, review, verify, ship
-                            #   Change 层步: plan, apply, review, verify, archive
-
-# Change 层执行记录（每次 apply 时追加）
-# 每个 Change 记录包含: { id, status, phase_ref, specs, tasks }
-# 每项格式见下方填写指引
-changes: []
-
-# 临时/紧急变更记录（非 Change 体系的修改）
-# 每项格式: { id, description, status, related_phase }
-adhoc: []
-
-# --- 前端变量说明 ---
-#
-# {{name}}       — 项目名称，从 project.yml 读取
-# {{date}}       — 当前日期，specwf 自动填充
-# {{phase-name}} — 当前 Phase 名称
-# {{change-name}}— 当前 Change 名称
-# {{step}}       — 当前工作流步骤名
----
-
-# {{name}} — 状态机
-
-## 当前位置
-
-<!-- 简要描述当前在项目流程中的位置 -->
-
-**项目层**: <!-- 如 "Milestone 1 — 用户认证系统实施中" -->
-**当前 Milestone**: {{current_milestone | "无"}}
-**当前 Phase**: {{current_phase | "无"}}
-**当前 Step**: <!-- 如 "Change 'add-email-login' apply 中" -->
-
-## 状态机
-
-<!-- 说明当前实体层的状态机路径和可选步 -->
-
-### 项目层状态机
-
-```
-initialized → requirements-defined → researched → roadmap-defined
-    → milestone-active → project-done / project-paused / project-aborted
-```
-
-### Phase 层状态机
-
-```
-discuss → research → split → [change执行循环] → ship
-                                   ↓
-               plan → apply → review → verify → archive
-                                    ← replan ←
-                                    ← reapply ←
-```
-
-### Change 层状态机
-
-```
-planned → applying → applied → reviewing → verifying → archived
-                         ↑← reapply  ←  ←  ←  ←
-```
-
-### 当前状态
-
-- **项目状态**: {{project.status}}
-- **Milestone 状态**: <!-- 如 "进行中 / 未开始 / 已完成" -->
-- **Phase 状态**: <!-- 如 "discuss 完成，research 进行中" -->
-- **Change 状态**: <!-- 如 "3 个 planned，2 个 applied，1 个 verifying" -->
-
-## 变更列表 (Changes)
-
-当前 Phase 下的所有 Change 及其状态一览。
-
-| Change ID | 描述 | 状态 | 关联 Specs |
-|-----------|------|------|------------|
-| <!-- change-1 --> | <!-- 简短描述 --> | planned / applying / applied / reviewing / verifying / archived / blocked | <!-- specs 文件路径 --> |
-| <!-- change-2 --> | <!-- ... --> | | |
-
-## 临时变更 (Ad-hoc)
-
-非 Change 体系内的暂存修改记录。
-
-| ID | 描述 | 状态 | 关联 Phase |
-|----|------|------|-----------|
-| <!-- adhoc-001 --> | <!-- 做了什么/为什么是 adhoc --> | open / resolved | <!-- 影响哪个 phase --> |
-
-## 历史
-
-<!-- 按时间增序记录所有关键状态变更事件。每次状态变更后追加一行。 -->
-
-- {{date | YYYY-MM-DD HH:mm}} — init: 创建 specwf 项目结构
-- <!-- 后续事件追加格式: -->
-- {{date}} — milestone {{milestone-name}} started
-- {{date}} — phase {{phase-name}} {{old-status}} → {{new-status}}
-- {{date}} — change {{change-name}} {{old-status}} → {{new-status}}
-
-## 状态变更检查清单
-
-每次变更状态时，请确认以下条件：
-
-### milestone 启动前
-- [ ] 前一 milestone 已 ship（或项目第一个）
-- [ ] roadmap 已定义
-- [ ] 资源/成员已就位
-
-### phase 启动前
-- [ ] 当前 milestone 中无冲突 phase
-- [ ] 依赖的前置 phase 已完成
-
-### phase split → apply
-- [ ] 所有 Change 已定义
-- [ ] Change 依赖图已确认无环
-- [ ] 每个 Change 都有 spec 和 plan
-
-### change apply → review
-- [ ] 所有 task 已实现并提交
-- [ ] RED→GREEN→REFACTOR 循环完整（behavior 类型）
-- [ ] 类型检查通过（tsc --noEmit）
-- [ ] 测试通过（vitest run）
-
-### change review → verify
-- [ ] 三重审查全部 PASS（或按 gate 配置通过）
-- [ ] 无未关闭的 reapply 标记
-
-### change verify → archive
-- [ ] 验证报告已生成
-- [ ] 无打开的 replan/reapply 回环
-- [ ] 代码认知已提取（archive 时触发 delta-spec 合并）
-
-### phase ship 前
-- [ ] 所有 Change 已 archived
-- [ ] phase summary 已生成
-- [ ] 文档已更新
-
----
-
-*state.md 由 specwf 自动管理。不要手动编辑 frontmatter 的缩进和层级结构。*

package/dist/templates/artifacts/summary.md

@@ -1,129 +0,0 @@
-# Phase Summary: {{phase-name}}
-
-> **Phase 起止**: {{start-date}} → {{end-date}}
-> **完成度**: {{percentage}}%（基于 completion checklist）
-
----
-
-## 完成状态
-
-<!--
-填写指引：
-基于验证结果给出最终完成状态。
-从以下状态中选择一个：
-- **Phase shipped**：所有 task 完成，验证全部通过
-- **Phase shipped with gaps**：核心功能完成，但标记了 gapped items
-- **Phase deferred**：本轮未完成已回滚，推迟到后续 phase
--->
-
-✅ **Phase shipped**。
-
-所有 Wave 的 task 已完成，验证项全部通过。本 phase 目标已达成。
-
----
-
-## Change 产出明细
-
-<!--
-填写指引：
-按 change 分列产出。每个 change 列出：
-- 产出文件清单（具体文件路径，不要泛泛说"若干文件"）
-- 关键实现决策（实现中做的关键决定）
-- 验证结果（测试 + 类型检查结果）
--->
-
-### Change: {{change-name-1}}
-
-**产出文件：**
-
-| 文件路径 | 说明 |
-|---|---|
-| `{{file-path-1}}` | {{说明}} |
-| `{{file-path-2}}` | {{说明}} |
-| `{{file-path-3}}` | {{说明}} |
-
-**关键实现决策：**
-- {{决策 1：如"选择在组件内部实现 getItemLayout 而非通过 props 传入"}}
-- {{决策 2：如"useScrollPerformance 用 RAF 而非 setInterval 采集帧率"}}
-
-**验证结果：**
-- `tsc --noEmit`：✅ 通过（0 error）
-- `vitest run`：✅ 通过（{{N}} tests, {{N}} passed）
-- lint：✅ 通过（0 warning）
-
----
-
-### Change: {{change-name-2}}
-
-**产出文件：**
-
-| 文件路径 | 说明 |
-|---|---|
-| `{{file-path-1}}` | {{说明}} |
-| `{{file-path-2}}` | {{说明}} |
-
-**关键实现决策：**
-- {{决策 1}}
-
-**验证结果：**
-- `tsc --noEmit`：✅ 通过
-- `vitest run`：✅ 通过
-- lint：✅ 通过
-
----
-
-## 验证结果
-
-<!--
-填写指引：
-填写验证汇总表。证据列可以是 CI 链接、截图、或命令执行结果摘要。
--->
-
-| 验证项 | 结果 | 证据 |
-|---|---|---|
-| 类型检查 (`tsc --noEmit`) | ✅ 通过 / ❌ 失败 | {{无错误/错误数及原因}} |
-| 单元测试 (`vitest run`) | ✅ 通过 / ❌ 失败 | {{N tests, N passed, N failed}} |
-| 集成测试 | ✅ 通过 / ❌ 失败 / N/A | {{测试范围说明}} |
-| lint 检查 | ✅ 通过 / ❌ 失败 | {{eslint / prettier 结果}} |
-| {{自定义验证项 1}} | ✅ / ❌ / N/A | {{证据}} |
-| {{自定义验证项 2}} | ✅ / ❌ / N/A | {{证据}} |
-
----
-
-## 偏差记录
-
-<!--
-填写指引：
-记录实现过程中与计划（proposal / design 文档）相比的偏差。
-每项偏差说明：原计划 vs 实际结果 + 原因 + 是否可接受。
-
-如果没有偏差，写：无偏差，实现完全符合设计文档。
--->
-
-| 原计划 | 实际结果 | 偏差原因 | 可接受？ |
-|---|---|---|---|
-| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
-| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
-| {{原计划描述}} | {{实际结果描述}} | {{为什么发生偏差}} | ✅ 是 / ❌ 否 / ⚠️ 有风险 |
-
----
-
-## 下一步
-
-<!--
-填写指引：
-基于本 phase 的完成情况和发现，建议下一 phase 或后续 action item。
-每个建议说明：做什么 + 为什么做 + 建议时机。
--->
-
-1. **{{下一步 action 1}}**：{{描述。如"在 Android 端进行列表滚动性能验证，确保 getItemLayout 效果一致"}}
-   - 原因：{{为什么需要做}}
-   - 建议时机：{{下个 sprint / 下个 phase 开始后两周内}}
-
-2. **{{下一步 action 2}}**：{{描述}}
-   - 原因：{{为什么需要做}}
-   - 建议时机：{{建议时机}}
-
-3. **{{下一步 action 3}}**：{{描述}}
-   - 原因：{{为什么需要做}}
-   - 建议时机：{{建议时机}}

package/dist/templates/artifacts/tasks.md

@@ -1,109 +0,0 @@
-# Tasks: {{name}}
-
-> **填表指引**：本文档将 design 拆解为按 wave 分组的可执行 task。每个 task 需包含 description、files、acceptance、可选的 depends_on 和 spec_ref。type:behavior 的 task 必须编写 RED 测试描述（GIVEN/WHEN/THEN 格式）。
-
----
-
-## TDD type 标注规则
-
-<!--
-每种 task 的 type 定义其 TDD 协议。
-type:behavior 必须走 RED→GREEN→REFACTOR，其余 type 直接实现。
--->
-
-| type | 含义 | TDD 协议 |
-|---|---|---|
-| `behavior` | 业务行为——实现一个具体的、可观测/可断言的业务功能 | **RED→GREEN→REFACTOR**（强制 TDD：先写测试 → 实现 → 重构） |
-| `config` | 配置文件——环境变量、CI/CD、lint、tsconfig 等 | 直接实现，无需 TDD |
-| `refactor` | 重构——不改变外部行为只改善内部结构 | 先验证已有测试通过 → 重构 → 再次验证 |
-| `docs` | 文档——README、API 文档、注释 | 直接实现，无需 TDD |
-| `scaffolding` | 骨架代码——新建模块的空壳、目录结构、模板文件 | 直接实现，无需 TDD |
-
-> **规则**：如果 task 的核心产出是"某个行为"（用户可感知或测试可断言），使用 `behavior`。如果只是"文件存在"或"配置生效"，使用 `config`/`scaffolding`。
-
----
-
-## Wave 1: {{wave-1-theme}}
-
-<!--
-Wave 是独立可验证的工作单元。一个 wave 内的 task 可能有依赖关系但整体封闭。
-每个 wave 完成后可执行验证（tsc + test pass）。
--->
-
-- [ ] task-{{id-1}}: [type:{{type}}] {{title}}
-  - **description**: {{详细描述：具体做什么、用什么方法、参考哪些文件/API}}
-  - **files**: {{文件路径列表，逗号分隔}}
-  - **acceptance**: {{可观测可断言的验收标准}}
-  - **depends_on**: [task-{{id-x}}] <!-- 可选：前置依赖 -->
-  - **spec_ref**: specs/{{domain}}/spec.md <!-- 可选：关联的规格文件 -->
-  {{if behavior}}
-  - ***RED 测试***:
-    ```
-    GIVEN {{前置条件}}
-    WHEN {{操作触发}}
-    THEN {{预期结果}}
-    ```
-  {{/if}}
-
-- [ ] task-{{id-2}}: [type:{{type}}] {{title}}
-  - **description**: {{详细描述}}
-  - **files**: {{文件路径列表}}
-  - **acceptance**: {{验收标准}}
-  {{if behavior}}
-  - ***RED 测试***:
-    ```
-    GIVEN {{前置条件}}
-    WHEN {{操作触发}}
-    THEN {{预期结果}}
-    ```
-  {{/if}}
-
----
-
-## Wave 2: {{wave-2-theme}}
-
-<!--
-如果设计超过一个 wave，在此添加。Wave 2 依赖 Wave 1 的产出。
--->
-
-- [ ] task-{{id-3}}: [type:{{type}}] {{title}}
-  - **description**: {{详细描述}}
-  - **files**: {{文件路径列表}}
-  - **acceptance**: {{验收标准}}
-  - **depends_on**: [task-{{id-1}}] <!-- 可选 -->
-  {{if behavior}}
-  - ***RED 测试***:
-    ```
-    GIVEN {{前置条件}}
-    WHEN {{操作触发}}
-    THEN {{预期结果}}
-    ```
-  {{/if}}
-
-- [ ] task-{{id-4}}: [type:{{type}}] {{title}}
-  - **description**: {{详细描述}}
-  - **files**: {{文件路径列表}}
-  - **acceptance**: {{验收标准}}
-  {{if behavior}}
-  - ***RED 测试***:
-    ```
-    GIVEN {{前置条件}}
-    WHEN {{操作触发}}
-    THEN {{预期结果}}
-    ```
-  {{/if}}
-
----
-
-## 验证
-
-<!--
-填写指引：
-所有 task 实现完毕后，在此 checklist 中逐项确认。
--->
-
-- [ ] `tsc --noEmit` 通过（或对应语言的类型检查）
-- [ ] `vitest run` 测试套件全部通过
-- [ ] 每个 wave 的验收标准已通过人工或自动化确认
-- [ ] 新增代码的 lint 检查通过
-- [ ] 未引入新的类型错误或告警

package/dist/templates/artifacts/verification.md

@@ -1,113 +0,0 @@
-# Verification: {{change-name}}
-
-> 验证时间: {{date}}
-
-## 测试结果
-
-列出所有执行过的测试及其结果。优先引用自动化测试结果（vitest、tsc 等），手工测试单独标注。
-
-| 测试名 | 类型 | 结果 | 耗时 | 备注 |
-|--------|------|------|------|------|
-| <!-- vitest run 等测试套件名 --> | <!-- unit / integration / e2e / manual / typecheck --> | ✅ 通过 / ❌ 失败 / ⏭ 跳过 | <!-- 如 "12s" --> | <!-- 特殊观察、不稳定测试等 --> |
-| tsc --noEmit | typecheck | ✅ | 5s | 无类型错误 |
-
-**填写指引：**
-- "类型"字段：`unit`（单元测试）、`integration`（集成测试）、`e2e`（端到端）、`manual`（手工验证）、`typecheck`（类型检查）
-- "结果"字段使用符号标记以便快速扫描：✅ = 通过、❌ = 失败、⏭ = 跳过、⚠ = 有警告但通过
-- "耗时"统一单位为秒（加 `s` 后缀）
-- 跳过或失败须在"备注"中说明原因
-
-## 需求覆盖检查
-
-对照 delta-specs 中的 Requirement 列表，逐项检查实现覆盖情况。
-
-| 需求 ID | 需求描述 | 覆盖状态 | 证据 |
-|---------|----------|----------|------|
-| <!-- REQ-001 等编号，按 proposal 或 spec 文档编号 --> | <!-- 需求原文摘要 --> | ✅ 已覆盖 / ❌ 未覆盖 / ⚠️ 部分覆盖 | <!-- 通过的测试名、代码链接、截图等 --> |
-
-**填写指引：**
-- 需求 ID 遵循 `REQ-{NNN}` 格式，与 delta-specs 中的编号一致
-- "覆盖状态"必须基于实际测试结果，而非代码审查印象
-- "证据"链接到具体的通过测试用例（如 `test/xxx.test.ts:12`）或手工验证记录
-- ⚠️ 部分覆盖须在备注或下方根因中说明未覆盖的边界
-
-## 决策覆盖检查
-
-对照 design.md 和 context.md 中的决策记录（D1、D2...），检查决策的落地情况。
-
-| 决策 ID | 决策内容 | 实现状态 | 证据 |
-|---------|----------|----------|------|
-| <!-- D1、D2 等编号 --> | <!-- 决策摘要 --> | ✅ 已实现 / ❌ 未实现 / ⚠️ 偏离 | <!-- 代码位置、文件名+行号等 --> |
-
-**填写指引：**
-- 决策 ID 与 design.md / context.md 中的编号一致
-- "实现状态"检查的是决策意图是否在代码中得到体现，不只是代码中是否包含关键字
-- ⚠️ 偏离须在下方根因诊断中分析原因
-
-## 目标达成检查
-
-对照 proposal.md 中的目标定义，逐项检查达成情况。
-
-| 目标项 | 达成状态 | 证据 |
-|--------|----------|------|
-| <!-- 从 proposal.md 提取的 must-haves 目标 --> | ✅ 达成 / ❌ 未达成 / ⚠️ 部分达成 | <!-- 测试结果、用户验证等 --> |
-
-## 根因诊断
-
-对于所有 ❌ 或 ⚠️ 的失败项（测试失败、未覆盖的需求、未实现的决策、未达成的目标），按照以下分类进行根因分析。
-
-### 失败项分类
-
-| 分类 | 含义 | 对应路由 |
-|------|------|----------|
-| 计划缺陷 | 设计错了或漏了 — 方案设计时不满足需求 | → replan（回 plan 重设计） |
-| 实现缺陷 | 代码写错了 — 设计正确但编码有误 | → reapply（回 apply 重实现） |
-| 规格缺陷 | spec 本身错了 — 需求描述错误或不完整 | → 标记 spec 待修，回 plan 修 spec |
-
-### 逐项根因分析
-
-<!-- 每列格式 -->
-#### 失败项 1: <测试名/需求ID/决策ID/目标项>
-
-- **现象**: <!-- 具体失败表现 -->
-- **根因分类**: <!-- 计划缺陷 / 实现缺陷 / 规格缺陷 -->
-- **根因分析**: <!-- 为什么错了，深层原因 -->
-- **影响范围**: <!-- 影响哪些模块、测试 -->
-- **修复建议**: <!-- 具体修复方向 -->
-
-#### 失败项 2: ...
-
-<!-- 每发现一个失败项，都按此格式记录。无失败项时写"所有项通过，无需根因分析。" -->
-
-## 路由建议
-
-根据根因诊断分类，勾选对应的处理路径：
-
-- [ ] **计划缺陷 → replan**: <!-- 具体列出哪些项需要回 plan 重新设计，以及重新设计的内容 -->
-- [ ] **实现缺陷 → reapply**: <!-- 具体列出哪些项需要回 apply 重写代码，以及修复方向 -->
-- [ ] **规格缺陷 → 标记 spec 待修，回 plan 修 spec**: <!-- 具体列出哪些 specs 需要修正 -->
-
-**路由原则：**
-- 一个失败项只能路由到一个路径（主路由），但可以影响其他路径（次影响）
-- 计划缺陷全部回 plan 重设计后重新 apply
-- 实现缺陷在 apply 修复后回到 review 重新审查对应项
-- 规格缺陷标为 spec-debt，在修 spec 后回 plan → apply 重新实现
-
-## 回环记录
-
-每次从 verify 返回到 plan/apply 的回环，在此记录。用于追踪迭代质量和效率。
-
-| 回环 # | 问题 | 路由 | 修复内容 | 验证结果 |
-|--------|------|------|----------|----------|
-| <!-- 1, 2, 3... --> | <!-- 触发回环的问题描述 --> | <!-- replan / reapply / spec-fix --> | <!-- 修改了哪些文件、改了什么 --> | ✅ 通过 / ❌ 仍需修复 |
-| | | | | |
-
-**填写指引：**
-- 每次回环递增编号（1、2、3...）
-- "路由"字段填写具体路径（如 `replan: D1 决策边界重新定义`）
-- "修复内容"要具体到文件和关键变更，方便后续审查
-- 回环超过 3 次时，应考虑简化 change 范围或重新评估方案可行性
-
----
-
-*Verification 报告由 specwf verify 阶段自动生成。每次验证结果覆盖前次。*

package/dist/templates/commands/adhoc.md

@@ -1,38 +0,0 @@
-# 临时 Change
-
-## 创建
-
-```bash
-specwf change new <change-name>
-```
-
-CLI 自动创建目录结构并生成模板文件。
-
-## 上下文
-
-```bash
-specwf context adhoc
-specwf state
-```
-
-## 推进
-
-完成 proposal 后：
-
-```bash
-specwf continue change <change-name>
-```
-
-`continue change <name>` 会读取该 change 的当前状态（proposal/planning/applying/reviewing/verifying/archived），输出下一步建议和 slash command。
-
-## 查看状态
-
-```bash
-specwf continue change <change-name>
-```
-
-## 归档
-
-```bash
-specwf archive specwf/changes/<change-name>
-```

package/dist/templates/commands/apply.md

@@ -1,20 +0,0 @@
-# 代码实现
-
-按 tasks.md 执行实现。使用 specwf-executor agent，分组并发。
-
-## TDD 协议
-
-type:behavior 任务走 RED→GREEN→REFACTOR。
-
-## 上下文
-
-```bash
-specwf context apply
-specwf state
-```
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/archive.md

@@ -1,21 +0,0 @@
-# 归档
-
-Delta-spec 合并 + 代码认知回灌。
-
-## 执行
-
-```bash
-specwf archive <change-path>
-```
-
-## 上下文
-
-```bash
-specwf state
-```
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/continue.md

@@ -1,27 +0,0 @@
-# 自动推进
-
-读 @specwf/state.md → 状态机确定下一步 → 自动执行。
-
-## 用法
-
-```bash
-# 从当前 active_context 推断下一步
-specwf continue
-
-# 查询指定 change 的下一步
-specwf continue change <name>
-```
-
-CLI 自动输出：
-- 当前位置
-- 当前步骤
-- 推荐下一步命令
-- Slash 命令（如有）
-- 是否需要子代理
-- 无下一步时的引导提示
-
-## 上下文
-
-```bash
-specwf state
-```

package/dist/templates/commands/discuss.md

@@ -1,24 +0,0 @@
-# Phase 讨论
-
-捕获实现决策，产出 CONTEXT.md。
-
-## 上下文
-
-```bash
-specwf context discuss
-specwf state
-```
-
-可参考：
-@specwf/roadmap.md
-@specwf/project.yml
-
-## 产出
-
-写入当前 phase 目录下的 context.md。
-
-## 下一步
-
-```bash
-specwf continue
-```

package/dist/templates/commands/grill.md

@@ -1,24 +0,0 @@
-# 需求探讨
-
-逐条向用户提问，直到所有需求细节达成共识。
-
-## 上下文
-
-```bash
-specwf context grill
-specwf state
-```
-
-可参考：
-@specwf/project.md
-@specwf/requirements.md
-
-## 产出
-
-更新 @specwf/requirements.md。
-
-## 下一步
-
-```bash
-specwf continue
-```