specwf 0.2.2 → 0.3.0

package/dist/templates/agents/verifier.md

@@ -1,129 +0,0 @@
-## 角色定义
-
-你是一个 specwf 的**测试验证专家**。
-
-你的核心职责是运行测试和验证流程，诊断失败根因，并根据失败类型路由到正确的修复路径（replan / reapply / 标记待修）。你是质量门控的最后防线。
-- 你运行完整的测试套件（单元测试 + 集成测试）
-- 你诊断每个失败的根因，不做表面修复
-- 你根据根因类型路由回正确的阶段
-- 你对环境问题做出与代码问题不同的处理
-
-## 核心约束
-
-- 所有产物写入 specwf/ 目录（相对于项目根目录）
-- 通过 bash 调用 specwf CLI 管理状态和转换（specwf state <subcommand>）
-- 遵守 project.yml 的 context 字段（注入到每步的上下文）
-- 遵守 conventions/ 下的项目约定（代码风格、命名规则、架构约定）
-- 所有产出文件使用中文撰写注释和文档
-- 不在 specwf/ 之外创建非代码产物
-
-## 执行流程
-
-按照以下分步流程严格执行：
-
-#### Step 1：读取上下文
-- 读取 change 的 proposal.md 了解目标和验收标准
-- 读取 delta-specs 了解规格约束
-- 读取 tasks.md 了解实现范围
-- 读取 reviews/ 下的审查报告了解已知问题
-
-#### Step 2：运行测试
-- 运行完整的测试套件：
-  - 单元测试（相关的测试文件）
-  - 集成测试（跨模块测试）
-- 记录测试结果摘要（总条数 / 通过 / 失败 / 跳过）
-- 测试命令通过 bash 执行，使用项目已有的测试框架
-- 如果测试框架有覆盖率报告，一并收集
-
-#### Step 3：诊断失败根因
-- 对每个测试失败做深入诊断：
-  1. 读取完整的错误栈（不只看第一行）
-  2. 读取失败测试的代码上下文
-  3. 读取被测试的实现代码
-  4. 检查相关的 spec 和 design 文档
-- 根因分为四类：
-  - **plan** — task 设计不完整、spec 与需求不一致、方案在技术上行不通
-  - **implement** — 代码实现错误、测试遗漏、未覆盖 edge case、与 spec 不一致
-  - **spec** — delta-spec 的描述与真实需求不一致，或 spec 本身错误
-  - **environment** — 环境配置、依赖版本、构建工具问题
-
-#### Step 4：路由回环决策
-根据根因分类路由到对应阶段：
-- plan → 路由到 replan（重新规划）
-  - 输出：需要修改的文档（proposal/design/tasks/specs）
-  - 附带具体的修改建议
-- implement → 路由到 reapply（重新实现）
-  - 输出：需要修复的文件列表和修复方案
-  - 附带具体的代码修改指引
-- spec → 标记 spec 待修（不触发回环）
-  - 在 spec 文件中标注 SPEC_NEEDS_REVIEW
-  - 待下一次对 spec 做整体 review 时处理
-- environment → 记录到 VERIFICATION.md 的 Environment 章节
-  - 不触发回环
-  - 如果阻塞了验证，标记为 human-needed
-
-#### Step 5：输出验证报告
-- 写入 VERIFICATION.md
-- 如果所有测试通过，结论为 PASS
-- 如果有可修复的失败，给出明确的路由路径
-- 如果有环境问题，标注在 Environment 章节
-
-## 偏差规则
-
-1. **根因分类**：每次测试失败必须诊断根因，按以下三类分类：
-   - 计划缺陷（plan）：task 设计不完整、spec 错误、方案不可行 → 路由到 replan
-   - 实现缺陷（implement）：代码错误、测试遗漏、未覆盖 edge case → 路由到 reapply
-   - 规格缺陷（spec）：delta-spec 描述与需求不一致 → 标记 spec 待修
-2. **环境问题 vs 代码问题**：环境/依赖/配置问题与代码问题分开处理。环境问题记录到 VERIFICATION.md 的 Environment 章节，不触发回环
-3. **诊断深度**：不满足于表面的测试失败信息。对每个失败：
-   - 查看完整的错误栈
-   - 检查相关代码上下文
-   - 确认是单一修改引起的还是累计的
-4. **重路由去重**：同一问题在回环后再次验证时，若根因未变化，不允许无限回环。连续 2 次回环未解决问题时，标记为 HUMAN_NEEDED
-
-- 所有产物写入 specwf/ 目录，不操作目录外的文件
-- 通过 bash 调用 specwf CLI 管理状态和转换
-- 遇到无法自动处理的问题时，记录到 issue 并通知主进程
-
-## 产物要求
-
-验证报告写入 specwf/VERIFICATION.md。
-
-### VERIFICATION.md 格式
-```markdown
-# Verification Report — Change <change-id>
-
-## Summary
-- 测试总数: N
-- 通过: N
-- 失败: N
-- 跳过: N
-
-## Failed Tests
-### <test-name-1> (file:line)
-- **错误信息**: <原始错误消息>
-- **根因分类**: plan | implement | spec | environment
-- **根因分析**: <详细分析>
-- **关联代码**: <文件:行号>
-- **路由建议**: replan | reapply | mark-spec-pending
-
-## Root Cause Analysis
-- <失败 1> → <根因分类> → <路由>
-
-## Routing Decision
-- 路由路径: replan / reapply / spec-pending / human-needed
-- 理由: <说明>
-
-## Environment Issues（如有）
-- <环境/依赖/配置问题列表>
-```
-
-## 验证标准
-
-完成验证后确认以下标准全部满足：
-- [ ] 所有测试（单元测试 + 集成测试）全部通过
-- [ ] 每个失败的根因已被诊断并分类（plan / implement / spec / environment）
-- [ ] 回环路由路径明确（replan / reapply / 标记待修）
-- [ ] VERIFICATION.md 包含测试摘要、失败详情、根因分析、路由建议
-- [ ] 验证覆盖了 delta-spec 的所有 SHALL/MUST 场景
-- [ ] 未留下不明的测试跳过或 @disabled 标记

package/dist/templates/artifacts/context.md

@@ -1,151 +0,0 @@
-# Phase Context: {{phase-name}}
-
-> **填表指引**：本文档在 Phase 启动时编写，记录该 Phase 的目标、关键决策和 Change 拆分。它既是实现者的工作指引，也是未来回顾时的依据。每节附填写指引。
-
----
-
-> **讨论时间**: {{date}}
-> **决策来源**: {{会议链接 / RFC 文档 / 讨论记录链接}}
-
----
-
-## Phase 目标
-
-<!--
-填写指引：
-1. 本 Phase 要完成什么？产出的 Changes 加起来覆盖了什么能力？
-2. 一句话概括目标，然后用 2-3 条具体说明。
-3. 本 Phase 的边界在哪里？
-
-格式示例：
-本 Phase 实现列表页滚动性能优化，具体包括：
-- 新增 OptimizedList 组件封装 FlatList
-- 新增 useScrollPerformance 滚动性能监控 hook
-- 更新 Performance Reporter 支持新数据字段
-- 不涉及后端 API 变更
--->
-
-{{phase-goal}}
-
----
-
-## 实现决策
-
-<!--
-填写指引：
-记录讨论中产生的关键决策。每个决策有独立编号（D1, D2, ...）。
-包含决策内容、理由、影响范围。
-
-不是所有实现细节都需要记录——只记录：
-- 有多个候选方案时做的选择
-- 影响后续 phase 或项目架构的决策
-- 与直觉相反的权衡
--->
-
-### D1: {{决策标题}}
-
-- **决策**: {{具体的决策内容。做什么？选什么方案？}}
-- **理由**: {{为什么选这个决策？关键约束是什么？}}
-- **影响文件/模块**: {{受影响的文件或模块列表}}
-
-### D2: {{决策标题}}
-
-- **决策**: {{具体的决策内容}}
-- **理由**: {{决策理由}}
-- **影响文件/模块**: {{受影响的文件或模块列表}}
-
-### D3: {{决策标题}}
-
-- **决策**: {{具体的决策内容}}
-- **理由**: {{决策理由}}
-- **影响文件/模块**: {{受影响的文件或模块列表}}
-
----
-
-## Decisions
-
-<!--
-填写指引：
-所有锁定决策的汇总表格。与上面的 D1/D2/... 章节保持一致。
--->
-
-| 编号 | 决策 | 理由 | 状态 |
-|---|---|---|---|
-| D1 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
-| D2 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
-| D3 | {{决策摘要}} | {{理由摘要}} | <span style="color:green">✓ Locked</span> |
-
-> 状态说明：**Locked** = 已确定且不可逆；**Deferred** = 延迟到后续 phase；**Open** = 待进一步讨论。
-
----
-
-## Deferred Ideas
-
-<!--
-填写指引：
-列出讨论过但决定暂不实施的想法。这是"idea parking lot"——防止好想法丢失。
-每个 idea 附：内容、暂缓原因、可能的实施时机（可选）。
--->
-
-1. **{{idea-title-1}}**：{{idea 描述}}
-   - 暂缓原因：{{为什么现在不做}}
-   - 可能时机：{{optional: 什么条件下可以重新考虑}}
-
-2. **{{idea-title-2}}**：{{idea 描述}}
-   - 暂缓原因：{{为什么现在不做}}
-   - 可能时机：{{optional: 什么条件下可以重新考虑}}
-
----
-
-## Claude's Discretion
-
-<!--
-填写指引：
-列出实现者在实现过程中可以自行判断而不需要额外沟通的方面。
-这给了实现者灵活性，同时避免"没问过"造成的意外。
--->
-
-- {{实现者可自行决定的方面 1，如：错误处理方式的选择}}
-- {{实现者可自行决定的方面 2，如：次要 UI 细节的视觉调整}}
-- {{实现者可自行决定的方面 3，如：局部变量命名风格}}
-
----
-
-## Change 拆分
-
-<!--
-填写指引：
-将 Phase 拆分为 1-3 个 Change。每个 Change 是一个独立可交付单元。
-格式：编号 + 名称 + 简短描述。
-如果 Change 之间有依赖关系，用箭头标注。
-
-格式示例：
-这个 Phase 包含 2 个 Change：
-
-1. **optimize-list-scroll** ← 核心性能优化（先做）
-   - 描述：实现 OptimizedList 组件 + getItemLayout 配置
-   - 依赖：无（基础 change）
-
-2. **add-scroll-metrics** ← 监控能力增强（后做）
-   - 描述：新增 useScrollPerformance hook + 数据上报
-   - 依赖：optimize-list-scroll（需要 OptimizedList 组件）
--->
-
-1. **{{change-name-1}}** — {{change-description-1}}
-   - 依赖：{{dependencies}} <!-- 无则填"无" -->
-
-2. **{{change-name-2}}** — {{change-description-2}}
-   - 依赖：{{dependencies}}
-
----
-
-## 非目标
-
-<!--
-填写指引：
-明确不属于本 Phase 的工作项。这些可能在 roadmap 上但不在本轮。
--->
-
-- {{非目标 1：为什么不在本 phase 做}}
-- {{非目标 2：为什么不在本 phase 做}}
-- {{非目标 3：为什么不在本 phase 做}}

package/dist/templates/artifacts/design.md

@@ -1,224 +0,0 @@
-# Design: {{name}}
-
-> **填表指引**：本文档是 Change Design，在 proposal 批准后编写，描述如何实现。每节均附填写指引，请按指引填写。写完此文档后进入 tasks 拆分解段。
-
----
-
-## 背景与目标
-
-<!--
-填写指引：
-1. 简要描述背景——什么上下文？有什么约束？
-2. 本设计的核心目标是什么？不超过 3 条。
-3. 与 proposal 中的 Intent 和 Must-haves 保持一致。
-
-示例：
-当前 FlatList 在 1000+ 条数据场景下帧率降至 20fps。
-本设计目标是：
-- 通过 getItemLayout + 固定行高将帧率恢复至 55fps+
-- 新增滚动性能监控，为后续优化提供数据依据
-- 不改变现有数据获取和渲染逻辑
--->
-
-{{background-and-goals}}
-
----
-
-## 技术方案
-
-### 架构图
-
-<!--
-填写指引：
-用 ASCII art 绘制模块/组件关系图，展示：
-- 新增模块与现有模块的关系
-- 数据流方向（用箭头标注）
-- 文件/模块边界
-
-示例：
-```
-┌─────────────────────────────────────────────────┐
-│                   页面层                         │
-│  ┌──────────┐    ┌──────────────────┐           │
-│  │ PageHome │───>│ OptimizedList    │           │
-│  │          │    │  (新增 wrapper)   │           │
-│  └──────────┘    └────────┬─────────┘           │
-│                           │                      │
-│                    ┌──────▼─────────┐            │
-│                    │ useScrollPerf  │            │
-│                    │ (新增 hook)     │            │
-│                    └──────┬─────────┘            │
-└───────────────────────────┼──────────────────────┘
-                            │
-                  ┌─────────▼─────────┐
-                  │   Performance     │
-                  │   Reporter        │
-                  │   (已有, 扩展)     │
-                  └───────────────────┘
-```
-
-绘图原则：
-- 方框标注模块/文件/组件
-- 箭头标注数据流或控制流
-- 标注"新增"、"修改"、"已有"区分
--->
-
-```text
-{{architecture-diagram}}
-```
-
-### 核心数据结构
-
-<!--
-填写指引：
-列出本设计新增或修改的关键类型/接口/数据结构定义。
-用 TypeScript 接口格式展示。每个类型附简要说明。
-
-格式示例：
-```typescript
-// 列表配置接口（新增）
-interface ListOptimizationConfig {
-  /** 固定行高，单位 px。设此值启用 getItemLayout */
-  itemHeight?: number;
-  /** 可见窗口外预渲染的行数（默认 10） */
-  windowSize?: number;
-  /** 是否启用滚动性能采集 */
-  enableScrollMetrics?: boolean;
-}
-
-// 滚动性能快照（新增）
-interface ScrollPerfSnapshot {
-  avgFps: number;
-  droppedFrames: number;
-  totalFrames: number;
-  scrollDistance: number;
-  timestamp: number;
-}
-```
--->
-
-{{data-structures}}
-
-### 数据流
-
-<!--
-填写指引：
-用步骤式描述说明数据如何流转。从触发源头到最终效果，每一步写清。
-
-格式示例：
-1. 用户下拉列表 → FlatList 触发 onScroll
-2. OptimizedList 读取 itemHeight 配置 → 启用 getItemLayout
-3. 布局引擎跳过动态测量 → 直接使用固定行高计算 offset
-4. useScrollPerformance 每 500ms 采集一次帧率
-5. 帧率数据 → Performance Reporter → 上报后端
-6. 渲染线程不再因布局计算阻塞 → 帧率恢复
--->
-
-{{data-flow}}
-
-### 接口设计
-
-<!--
-填写指引：
-列出本设计对外暴露的 API 签名，包括：
-- 函数/方法名
-- 参数列表（名称 + 类型 + 说明）
-- 返回值类型
-- 是否 async/sync
-
-格式示例：
-
-```typescript
-// OptimizedList 组件 props
-interface OptimizedListProps<T> {
-  data: T[];
-  renderItem: (item: T, index: number) => React.ReactElement;
-  /** 固定行高（px），必填以启用 getItemLayout */
-  itemHeight: number;
-  /** 窗口外预渲染行数（可选，默认 10） */
-  windowSize?: number;
-  /** 启用滚动性能采集（可选，默认 false） */
-  enableScrollMetrics?: boolean;
-  /** 滚动性能回调（可选） */
-  onPerfSnapshot?: (snapshot: ScrollPerfSnapshot) => void;
-}
-
-// useScrollPerformance hook
-function useScrollPerformance(
-  listRef: React.RefObject<FlatList>,
-  options?: { intervalMs?: number }
-): { avgFps: number; isJanking: boolean };
-```
--->
-
-{{api-signatures}}
-
----
-
-## 文件清单
-
-<!--
-填写指引：
-列出所有需创建或修改的文件，用表格组织。
--->
-
-| 文件路径 | 内容描述 | 操作 |
-|---|---|---|
-| `{{file-path-1}}` | {{description}} | 创建 |
-| `{{file-path-2}}` | {{description}} | 修改 |
-| `{{file-path-3}}` | {{description}} | 创建 |
-
----
-
-## 测试策略
-
-<!--
-填写指引：
-按测试层次描述覆盖范围。不需要写具体用例——tasks 文件负责拆解。
--->
-
-### 单元测试
-- <!-- 哪些模块需要单元测试？需要 mock 什么？ -->
-
-### 集成测试
-- <!-- 哪些流程需要集成测试？需要准备什么 fixture？ -->
-
-### TDD 任务
-- <!-- 列出需要走 RED→GREEN→REFACTOR 的 type:behavior 任务 -->
-
----
-
-## 备选方案
-
-<!--
-填写指引：
-列出评估过但未选择的方案，说明为什么放弃。
-
-| 方案 | 优点 | 缺点 | 不选原因 |
-|---|---|---|---|
-| {{方案 A}} | {{优点}} | {{缺点}} | {{原因}} |
-| {{方案 B}} | {{优点}} | {{缺点}} | {{原因}} |
--->
-
-| 方案 | 优点 | 缺点 | 不选原因 |
-|---|---|---|---|
-| {{alt-name-1}} | {{pros}} | {{cons}} | {{reason}} |
-| {{alt-name-2}} | {{pros}} | {{cons}} | {{reason}} |
-
----
-
-## 风险点
-
-<!--
-填写指引：
-识别实现风险并评估影响。
-
-| 风险 | 概率 | 影响 | 缓解措施 |
-|---|---|---|---|
-| {{风险描述}} | 高/中/低 | 高/中/低 | {{措施}} |
--->
-
-| 风险 | 概率 | 影响 | 缓解措施 |
-|---|---|---|---|
-| {{risk-1}} | {{probability}} | {{impact}} | {{mitigation}} |
-| {{risk-2}} | {{probability}} | {{impact}} | {{mitigation}} |

package/dist/templates/artifacts/goal-review.md

@@ -1,95 +0,0 @@
-# Goal Review: {{change-name}}
-
-> 审查时间: {{date}}
-> 审查者: {{reviewer | agent/human}}
-
-## Change 目标
-
-从 proposal.md 中提取的 must-haves（强制目标）和 nice-to-haves（非强制目标）列表。目标应以可观测、可验证的方式表述。
-
-### Must-haves（强制目标）
-
-<!-- 逐条列出 proposal.md "Scope" → "In scope" 中的条目，或 proposal.md 中标记为必须实现的目标 -->
-
-1. **目标 1**: <!-- 可观测行为描述，如"用户可以通过邮箱注册账号" -->
-2. **目标 2**: <!-- 如"未登录用户无法访问 /dashboard" -->
-3. **目标 3**: <!-- ... -->
-
-### Nice-to-haves（可选目标）
-
-<!-- 列出 proposal.md 中标记为可选的目标，或 Scope → "Out of scope" 之外的合理期望 -->
-
-1. **期望 1**: <!-- ... （如果未实现不需要 FAIL） -->
-
-**填写指引：**
-- 目标必须从 proposal.md 原文提取，不自行发明或解释
-- 目标必须以可观测行为描述——不写"模块设计好"而写"接口签名满足 X 和 Y"
-- 强制目标（must-haves）和可选目标（nice-to-haves）分开列出
-- 如果 proposal.md 没有明确定义 must-haves，则回退到 tasks.md 中的所有 task acceptance 条件
-
-## 达成情况
-
-每行对应一个目标项，检查代码实现是否实际产生了预期的可观测行为。
-
-| 目标项 | 可观测行为 | 达成状态 | 证据 | 备注 |
-|--------|------------|----------|------|------|
-| 目标 1: | <!-- 预期的可观测行为描述 --> | ✅ 达成 / ❌ 未达成 / ⚠️ 部分达成 | <!-- 测试通过、演示录屏、截图、日志等 --> | <!-- 偏离项说明 --> |
-| 目标 2: | <!-- ... --> | ✅ 达成 | <!-- test/login.test.ts:12-30 PASS --> |  |
-| API 响应时延 < 200ms | 接口 95 分位响应时间 | ❌ 未达成 | loadtest result: p95=450ms | 已在 plan 中添加性能优化任务 |
-
-**达成状态判定标准：**
-
-| 状态 | 标准 |
-|------|------|
-| ✅ 达成 | 对应的可观测行为已经实现并通过验证 |
-| ❌ 未达成 | 目标对应的行为没有实现或验证失败 |
-| ⚠️ 部分达成 | 主要行为实现但存在偏差（如缺少某些边界处理） |
-
-**证据要求：**
-- ✅ 必须附证据——通过的测试用例、截图、性能测试数据、用户验收记录等
-- 不写"代码已实现"作为证据——要证明的是"行为可观测"，而不是"代码存在"
-- ❌ 和 ⚠️ 必须在下方的"未达成项详情"中分析根因
-
-## 未达成项详情
-
-对于 ❌ 未达成 和 ⚠️ 部分达成 的目标项，逐项展开分析。
-
-### {{目标项}}: {{目标描述}}
-
-- **预期行为**: <!-- proposal.md 或 tasks.md 中定义的验收标准 -->
-- **实际行为**: <!-- 当前代码的行为 -->
-- **差距分析**: <!-- 为什么有差距 -->
-- **根因**: <!-- 是设计漏了、实现遗漏、还是需求变更了 -->
-- **修复方向**: <!-- 达成目标具体需要做啥 -->
-- **是否影响其他目标**: <!-- 修复这个会不会导致其他目标失效 -->
-
-### <!-- 下一个未达成项 -->
-
-<!-- 无 ❌/⚠️ 项时写"所有目标均已达成，无不达成项。" -->
-
-## Scope Creep 检查
-
-检查实现中是否包含了 proposal.md 范围之外的功能。
-
-| 发现的功能 | 对应代码位置 | 是否可接受 | 说明 |
-|------------|-------------|------------|------|
-| <!-- 额外实现的功能 --> | <!-- 文件+行号 --> | 可接受 / 需移除  | <!-- 理由 --> |
-
-**填写指引：**
-- 超出 proposal 范围的功能不等于坏代码，但需要在 change 上下文中评估
-- 如果 scope creep 影响了原目标的交付或增加了风险，应标记为"需移除"
-- 发现非预期的 side effect（如修改了不该改的模块）也在此记录
-
-## 结论
-
-- [ ] **PASS** — 所有 must-haves 目标达成，无 scope creep 风险
-- [ ] **FAIL** — 存在未达成的 must-haves 目标：
-  - <!-- 列出具体未达成的目标项 -->
-  - <!-- 建议：窄化 change 范围 or 增加 commit 完成剩余目标 -->
-
-**审查总结：**
-- 总目标: <!-- N --> 个 must-have, <!-- M --> 个 nice-to-have
-- 达成: <!-- 数量 --> / <!-- N --> must-haves 完成
-- 未达成: <!-- 数量 --> / <!-- N -->
-- Scope Creep: <!-- 数量 --> 处
-- 整体评估: <!-- 该 change 是否值得发布 / 需要修补 / 建议拆分 -->