specwf 0.2.2 → 0.3.0

package/dist/templates/artifacts/project.yml

@@ -1,117 +0,0 @@
-# specwf project configuration
-# Generated by specwf init
-# 
-# 本文件定义项目级别的工作流配置。修改后的配置在下次 specwf 命令执行时生效。
-
-# 配置文件格式版本号 —— 由 specwf 管理，不要手动修改
-version: 1
-
-# ============================================================
-# 平台配置
-# ============================================================
-# 项目运行的目标平台列表。specwf 根据平台加载对应的集成适配器。
-# 可选值:
-#   - omp         Oh My Pi 集成（默认，含 specwf CLI 完整支持）
-#   - claude      Claude Code 环境中运行
-#   - standalone  纯 CLI 模式，无平台依赖
-platform:
-  - omp
-
-# ============================================================
-# 项目配置模板
-# ============================================================
-# 项目级别设定。profile 决定默认开启哪些功能集合。
-#   可选值: standard, minimal, advanced, custom
-#   standard  — 开启所有基础功能（research/tdd/triple_review/auto_advance/spec_injection）
-#   minimal   — 只开启最基础流程，适合实验性项目
-#   advanced  — 在 standard 基础上增加 plan_check、严格校验
-#   custom    — 自行通过 workflow.* 开关配置
-profile: standard
-
-# ============================================================
-# 项目描述上下文
-# ============================================================
-# 项目描述文本，会被注入到每个 specwf agent 的系统提示中，作为项目背景知识。
-# 请填写项目名称、技术栈、测试框架等关键信息。
-# 格式: YAML 多行字符串（| 注意缩进）
-context: |
-  项目: {{name}}
-  技术栈: <!-- TypeScript, Node.js, React, PostgreSQL 等 -->
-  测试框架: <!-- vitest, jest, playwright 等 -->
-
-# ============================================================
-# 工作流开关
-# ============================================================
-# 各阶段的启用/禁用。true=启用，false=跳过。
-# 单个开关设置为 false 后，对应阶段在 specwf run 时被跳过但仍可通过 specwf run --step <name> 显式执行。
-workflow:
-  # 是否启用 Plan 前的调研阶段（research.md）
-  research: true
-  # 是否在 plan 生成后自动执行 plan_check（验证 plan 完整性）
-  plan_check: true
-  # 是否强制 TDD（type:behavior 任务必须 RED→GREEN→REFACTOR）
-  tdd: true
-  # 是否启用三重并行审查（规格审查 + 质量审查 + 目标审查）
-  triple_review: true
-  # 审查全部通过后是否自动前进到 verify 阶段
-  auto_advance: true
-  # 是否在执行 change 时注入全局 specs/conventions 到 agent 提示
-  spec_injection: true
-
-# ============================================================
-# 审查阶段配置
-# ============================================================
-review:
-  # 审查阈值模式：
-  #   all-pass          — 三重审查全部 PASS 才能进入 verify（最严格）
-  #   severity          — 没有 HIGH/CRITICAL 问题即可
-  #   report-only       — 审查结果仅供参考，不阻塞
-  #   majority-vote     — 三份报告有两份以上 PASS 即可推进
-  gate: all-pass
-  # 是否并行执行三种审查（true=同时启动三个 reviewer，false=串行）
-  parallel: true
-
-# ============================================================
-# Change 执行配置
-# ============================================================
-change:
-  # 多 Change 并发执行模式：
-  #   single            — 每次只执行一个 Change
-  #   dependency-graph  — 按依赖图调度 Change（默认，推荐的平衡模式）
-  #   concurrent        — 不做依赖检查，全部 Change 同时执行
-  parallel: dependency-graph
-  # 是否隔离 Change 的执行环境（git worktree / 临时目录等）
-  isolation: true
-
-# ============================================================
-# Git 版本管理配置
-# ============================================================
-git:
-  # 分支策略:
-  #   none        — 不自动管理分支，在当前分支上直接提交
-  #   auto        — 自动为每个 Change/Phase 创建和切换分支
-  #   per-change  — 每个 Change 创建独立分支
-  #   per-phase   — 每个 Phase 创建独立分支
-  branching: none
-  # 完成 Phase 时是否创建 git tag
-  create_tag: true
-
-# ============================================================
-# 规范注入配置
-# ============================================================
-conventions:
-  # 是否在 apply 时将全局 conventions/ 注入到 agent 提示
-  inject: true
-
-# ============================================================
-# LLM 模型配置（可选）
-# ============================================================
-# 指定不同阶段的模型。
-# 格式: <阶段名>: <模型 ID>
-# 模型 ID 取决于运行平台和本地可用的模型
-# 示例:
-#   plan: claude-sonnet-4
-#   apply: claude-haiku-3.5
-#   review: gpt-4o
-# 留空 {} 使用平台默认模型
-models: {}

package/dist/templates/artifacts/proposal.md

@@ -1,124 +0,0 @@
-# Proposal: {{name}}
-
-> **填表指引**：本文档是 Change Proposal，用于在实现前对齐变更的意图、范围和方案。每节均附填写指引，请按指引完整填写。完成后约 1-3 位 reviewer 会评审本 proposal 后再进入 design 阶段。
-
----
-
-## Intent
-
-<!--
-填写指引：
-说明为什么要做这个变更，回答以下问题：
-1. 当前系统存在什么具体问题或缺失什么能力？
-2. 这个问题影响谁（用户/开发者/运维）？影响程度如何？
-3. 不做这个变更会有什么后果？
-4. 这个是 bug fix / feature / tech debt / perf improvement？
-5. 是否关联某个已知 issue、用户反馈、或性能指标？（可附 issue 链接）
-
-示例：
-用户反馈在列表页滑动时出现明显卡顿（60fps→20fps），经 profiling
-定位为 FlatList 未配置 getItemLayout 导致布局计算 O(n²)。
-本变更为性能修复，目标是将列表滚动帧率恢复至 55fps+。
--->
-
-{{intent}}
-
----
-
-## Scope
-
-<!--
-填写指引：明确界定"做什么"和"不做什么"。
--->
-
-### In scope
-
-<!--
-列出本变更涵盖的所有功能点或改动项。
-每项一行，用动词开头描述具体变更。
-
-格式示例：
-- 在列表页下拉刷新时增加骨架屏加载状态
-- 新增 `useScrollPerformance` hook，提供 scroll metrics 采集
-- 为 `<UserCard>` 组件添加 memo + 纯组件优化
--->
-
-{{in-scope-items}}
-
-### Out of scope
-
-<!--
-明确排除的改动，防止 scope creep。
-每项一行，说明为什么不在本次做。
-
-格式示例：
-- 首页的骨架屏改造（已规划在下一 phase 处理）
-- 服务端 API 分页改造（与客户端性能问题无关）
-- Android 端列表性能优化（platform-specific，需单独调研）
--->
-
-{{out-of-scope-items}}
-
----
-
-## Approach
-
-<!--
-填写指引：从宏观描述技术方案方向，涵盖以下方面：
-1. **架构方向**：改动落在哪一层（UI / ViewModel / Service / Store）？是否需要新建模块？
-2. **关键库选型**：是否引入新依赖？替换或升级现有依赖？选择理由？
-3. **数据流方向**：数据如何从源头到达 UI？状态管理变更？
-4. **兼容性**：向后兼容策略？是否需要 migration？
-5. **可测试性**：方案中是否为测试留有入口（依赖注入 / mock 点）？
-
-不需要在此写详细实现——design 文档负责。这里写"方向"即可。
-
-示例：
-- UI 层：在 FlatList 组件外层封装 OptimizedList，内部配置 getItemLayout
-  和 windowSize；ViewModel 层新增列表性能监控数据上报点
-- 后端接口：不涉及，所有数据流不变
-- 测试策略：新增 useScrollPerformance 单元测试 + 列表渲染性能 benchmark
--->
-
-{{approach}}
-
----
-
-## Must-haves
-
-<!--
-列出 3-7 条可观测、可验证的必须达成的行为。
-每条必须是具体声明，不模糊。
-写完后 reviewer 应能用这些条件判断是否通过。
-
-填写指引：
-- 每行以 "MUST" / "SHALL" 开头（英文）或 "必须" 开头（中文）
-- 可观测：打开页面能看到，终端命令可检查，测试可断言
-- 可验证：reviwer 能通过操作/命令确认
-
-示例：
-- 列表页滚动帧率在 1000 条数据下不低于 55fps
-- 下拉刷新时骨架屏在 200ms 内显示
-- 新增 useScrollPerformance 的单元测试覆盖率达到 90%+
--->
-
-{{must-haves}}
-
----
-
-## Non-goals
-
-<!--
-明确非目标，防止 reviewer 误判"为什么没做某事"。
-每项一行。
-
-不同于 Out of scope（不在此 change 的范围内），
-Non-goals 是可能被误以为在范围内但明确不做的具体目标。
-
-示例：
-- 不追求 Android 端列表性能在本 change 中提升
-- 不改变现有列表的分页逻辑
-- 不新增 UI 组件库依赖
--->
-
-{{non-goals}}

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

@@ -1,131 +0,0 @@
-# Quality Review: {{change-name}}
-
-> 审查时间: {{date}}
-> 审查者: {{reviewer | agent/human}}
-
-## 审查范围
-
-列出本次质量审查覆盖的代码文件范围。
-
-- **TypeScript/源代码**: <!-- 如 `src/**/*.ts`（排除生成的） -->
-- **测试代码**: <!-- 如 `test/**/*.test.ts` -->
-- **配置文件**: <!-- 如 `*.config.ts`、`tsconfig.json` -->
-- **其他**: <!-- 如 SQL 脚本、Dockerfile、CI 配置等 -->
-
-**填写指引：**
-- 范围应列出文件 glob 或手动文件列表，确保可复现
-- 明确指出本次审查涉及新增、修改、删除的文件
-- 如果只审查 diff，写"新增代码行: N, 修改代码行: M"
-
-## 审查结果
-
-按四个维度分别检查。各维度独立打分，综合决定最终结论。
-
-### Bug 检查
-
-检查代码中是否存在逻辑错误、边界条件漏处理、竞态条件等问题。
-
-| 文件 | 问题 | 严重度 | 状态 |
-|------|------|--------|------|
-| <!-- 文件名+行号 --> | <!-- 问题描述 --> | critical / high / medium / low | 未修复 / 已修复 / 误报 |
-
-**典型检查项：**
-- [ ] 空值 / undefined / null 路径是否处理
-- [ ] 边界条件（数组为空的特殊值、最大/最小值）
-- [ ] 异步操作的竞态条件（race condition、未 await）
-- [ ] 错误处理是否完整（try/catch 是否合适）
-- [ ] 状态机转换是否合法
-- [ ] 循环终止条件是否可能无限
-
-### 安全检查
-
-检查代码中的安全漏洞和敏感信息泄露。
-
-| 文件 | 问题 | 严重度 | 状态 |
-|------|------|--------|------|
-| <!-- 文件名+行号 --> | <!-- 问题描述 --> | critical / high / medium / low | 未修复 / 已修复 / 误报 |
-
-**典型检查项：**
-- [ ] 用户输入是否经过校验或清洗（注入风险）
-- [ ] 敏感信息（token、key、密码）是否被硬编码或日志输出
-- [ ] 权限检查是否缺失
-- [ ] 文件路径拼接存在遍历风险
-- [ ] 依赖是否存在已知 CVE（已知漏洞）
-- [ ] SQL / shell 命令拼接是否有注入风险
-
-### 规范检查
-
-检查代码是否符合项目约定的编码风格和模式。
-
-| 文件 | 问题 | 严重度 | 状态 |
-|------|------|--------|------|
-| <!-- 文件名+行号 --> | <!-- 问题描述 --> | critical / high / medium / low | 未修复 / 已修复 / 误报 |
-
-**典型检查项：**
-- [ ] 命名是否符合约定（camelCase / PascalCase / kebab-case）
-- [ ] 类型是否正确使用（有无不必要的 `any`）
-- [ ] lint 规则遵守情况（eslint 规则违反）
-- [ ] 项目既有模式是否被遵循（如请求处理模式、错误处理模式）
-- [ ] 文件组织是否符合模块结构约定
-- [ ] import 路径是否符合项目别名配置
-
-### 性能检查
-
-检查代码中可能影响性能的写法。
-
-| 文件 | 问题 | 严重度 | 状态 |
-|------|------|--------|------|
-| <!-- 文件名+行号 --> | <!-- 问题描述 --> | critical / high / medium / low | 未修复 / 已修复 / 误报 |
-
-**典型检查项：**
-- [ ] 不必要的内存分配（循环中创建对象/数组）
-- [ ] N+1 查询或不必要的重复请求
-- [ ] 大对象不必要的深拷贝
-- [ ] DOM 操作过于频繁
-- [ ] 未使用缓存的热路径
-- [ ] 长列表未分页或虚拟滚动
-
-## 严重度定义
-
-| 严重度 | 定义 | 对结论的影响 |
-|--------|------|-------------|
-| **critical** | 功能被完全破坏、安全漏洞可被利用、数据可能丢失 | 直接 FAIL |
-| **high** | 主要路径存在 bug、明显的安全风险、轻微的功能异常 | 强烈建议修复后再通过；如果可以证明该路径不触发的则降级 |
-| **medium** | 边缘情况下的问题、不规范但无功能影响、重构建议 | 不阻塞，记录为 tech debt |
-| **low** | 样式偏好、注释不完整、可读性建议 | 仅供参考，不记录 tech debt |
-
-## 不通过项详情
-
-只记录状态为"未修复"且严重度 ≥ medium 的问题。low 严重度的问题仅汇总数量。
-
-### {{文件:行号}}: {{问题摘要}}
-
-- **维度**: <!-- Bug / Security / Convention / Performance -->
-- **严重度**: <!-- critical / high / medium -->
-- **问题描述**: <!-- 为什么这是问题 -->
-- **代码位置**:
-  ```typescript
-  // 定位到的代码片段（贴关键行）
-  ```
-- **影响分析**: <!-- 什么条件下会触发此问题 -->
-- **不触发证明**（可选）: <!-- 如果声称"不会在实际中触发"，提供证据 -->
-
-### <!-- 下一个问题 -->
-
-<!-- 无不通过项时写"未发现严重度 ≥ medium 的问题。" -->
-
-## 结论
-
-- [ ] **PASS** — 代码质量达标，无 critical/high 未修复项
-- [ ] **FAIL** — 存在质量问题：
-  - **critical** 未修复: <!-- 数量 -->
-  - **high** 未修复: <!-- 数量 -->
-  - **medium** 未修复: <!-- 数量（参考，不阻塞） -->
-  - **low** 未修复: <!-- 数量（仅供参考） -->
-
-**审查总结：**
-- BUG: <!-- 发现了 X 个 bug，其中 critical/high N 个 -->
-- 安全: <!-- 发现了 X 个安全问题，其中 critical/high N 个 -->
-- 规范: <!-- 主要规范问题概述 -->
-- 性能: <!-- 主要性能问题概述 -->
-- 整体结论: <!-- 高度概括项目当前代码质量状态 -->

package/dist/templates/artifacts/research.md

@@ -1,127 +0,0 @@
-# Phase Research: {{phase-name}}
-
-> **调研时间**: {{date}}
-> **调研者**: {{作者}}
-> **状态**: {{进行中 / 已完成 / 待补充}}
-
----
-
-## 调研方向
-
-<!--
-填写指引：
-每个调研方向独立一节。对每个方向列出：
-- 调研问题：本次调研要回答的具体问题
-- 候选方案：备选方案的对比表格
-- 结论：推荐哪个方案及理由
-- 来源：参考链接/文档
-
-每节回答一个独立的技术或业务问题。如果某一方向没有涉及 n 个候选方案，则不需要对比表格。
--->
-
-### 方向 1: {{调研主题 1}}
-
-#### 调研问题
-- {{问题 1：如 "React Native 0.73 的 getItemLayout 对动态高度列表的支持程度？"}}
-- {{问题 2：如 "是否需要在 Android 上关闭 accessibility 以提升列表性能？"}}
-
-#### 候选方案
-
-| 方案 | 优点 | 缺点 | 成熟度 | 许可证 |
-|---|---|---|---|---|
-| {{方案 A 名称}} | {{优点列表}} | {{缺点列表}} | {{GA / Beta / Alpha}} | {{MIT / Apache / 专有}} |
-| {{方案 B 名称}} | {{优点列表}} | {{缺点列表}} | {{GA / Beta / Alpha}} | {{MIT / Apache / 专有}} |
-| {{方案 C 名称}} | {{优点列表}} | {{缺点列表}} | {{GA / Beta / Alpha}} | {{MIT / Apache / 专有}} |
-
-#### 结论
-
-{{推荐方案和理由。包含：推荐什么、为什么它优于其他方案、什么条件下应该重新评估。}}
-
-#### 来源
-
-- {{链接 1：官方文档 / RFC / issue}}
-- {{链接 2：社区文章 / 博客}}
-- {{链接 3：相关工具仓库}}
-
----
-
-### 方向 2: {{调研主题 2}}
-
-#### 调研问题
-- {{问题 1}}
-- {{问题 2}}
-
-#### 候选方案
-
-| 方案 | 优点 | 缺点 | 成熟度 | 许可证 |
-|---|---|---|---|---|
-| {{方案 A 名称}} | {{优点}} | {{缺点}} | {{成熟度}} | {{许可证}} |
-| {{方案 B 名称}} | {{优点}} | {{缺点}} | {{成熟度}} | {{许可证}} |
-
-#### 结论
-
-{{推荐方案和理由}}
-
-#### 来源
-
-- {{链接 1}}
-- {{链接 2}}
-
----
-
-### 方向 3: {{调研主题 3}}
-
-#### 调研问题
-- {{问题 1}}
-
-#### 候选方案
-
-| 方案 | 优点 | 缺点 | 成熟度 | 许可证 |
-|---|---|---|---|---|
-| {{方案 A 名称}} | {{优点}} | {{缺点}} | {{成熟度}} | {{许可证}} |
-| {{方案 B 名称}} | {{优点}} | {{缺点}} | {{成熟度}} | {{许可证}} |
-
-#### 结论
-
-{{推荐方案和理由}}
-
-#### 来源
-
-- {{链接 1}}
-
----
-
-## 推荐方案汇总
-
-<!--
-填写指引：
-将所有方向的推荐汇总为一张表格，方便快速参考。
--->
-
-| 类别 | 推荐方案 | 备选方案 | 关键理由 |
-|---|---|---|---|
-| {{类别 1：如"列表性能优化"}} | {{推荐方案}} | {{备选方案}} | {{选择该方案的核心原因}} |
-| {{类别 2：如"性能监控方案"}} | {{推荐方案}} | {{备选方案}} | {{选择该方案的核心原因}} |
-| {{类别 3}} | {{推荐方案}} | {{备选方案}} | {{选择该方案的核心原因}} |
-
----
-
-## 陷阱与注意事项
-
-<!--
-填写指引：
-列出调研过程中发现的已知陷阱、常见错误、容易被忽略的边缘情况。
-这是最有价值的信息——减少实现者踩坑的概率。
--->
-
-1. **{{陷阱标题 1}}**：{{描述。如："Android 端 FlatList 的 getItemLayout 在 item 高度不一致时会导致滚动位置跳跃。如果必须支持动态高度，考虑改用 CellRendererComponent + 缓存测量的高度。"}}
-   - 影响范围：{{哪些模块/平台受影响}}
-   - 缓解方法：{{如何避免或处理}}
-
-2. **{{陷阱标题 2}}**：{{描述}}
-   - 影响范围：{{影响范围}}
-   - 缓解方法：{{缓解方法}}
-
-3. **{{陷阱标题 3}}**：{{描述}}
-   - 影响范围：{{影响范围}}
-   - 缓解方法：{{缓解方法}}

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

@@ -1,84 +0,0 @@
-# Spec Review: {{change-name}}
-
-> 审查时间: {{date}}
-> 审查者: {{reviewer | agent/human}}
-
-## 审查范围
-
-列出本次审查覆盖的输入文件清单。
-
-- **delta-specs 文件**:
-  - `specwf/changes/{{change-name}}/specs/*.md` — <!-- 具体文件名，如 `req-api.md`、`req-auth.md` -->
-- **实现文件**:
-  - <!-- 实现代码路径，如 `src/lib/xxx.ts`、`src/modules/xxx/` -->
-- **测试文件**:
-  - <!-- 如 `test/lib/xxx.test.ts` -->
-- **相关规格文件**（全局 specs/）:
-  - <!-- 如 `specs/conventions/coding-standards.md` -->
-
-**填写指引：**
-- 审查范围应以文件列表形式明确给出，不写模糊的"所有实现文件"
-- 只审查当前 change 涉及的 specs 和 files，不审查全局无关的规格
-- 如果 change 没有新增 delta-specs（纯 refactor/docs），注明"本 change 无新增 specs"
-
-## 审查结果
-
-每条记录对应 delta-specs 中的一个 Requirement 或 Scenario，逐项审查。
-
-| 规格项 | SHALL/MUST 关键词 | 场景 | 实现状态 | 证据 | 备注 |
-|--------|-------------------|------|----------|------|------|
-| <!-- SHALL-001 或 REQ-001 --> | <!-- SHALL / MUST / SHOULD / MAY --> | <!-- GIVEN/WHEN/THEN 场景摘要，或具体行为描述 --> | ✅ 满足 / ❌ 不满足 / ⚠️ 部分满足 | <!-- 代码行号引用、测试用例名 --> | <!-- 观察到的偏差、异常等 --> |
-| | | | | | |
-
-**填写指引：**
-
-### 规格项命名
-- 直接引用 delta-specs 中的 Requirement ID（如 `REQ-001`）或 Scenario 标题
-- 如果 delta-specs 没有编号，按文件+序号引用（如 `req-api.md#L12`）
-
-### SHALL/MUST 关键词含义
-| 关键词 | 含义 | 审查要求 |
-|--------|------|----------|
-| SHALL / MUST | 强制性要求，必须实现 | ✅ 必须满足，否则 FAIL |
-| SHOULD | 建议性要求，推荐实现 | ⚠️ 不满足时标注但可不 FAIL |
-| MAY | 可选要求 | 不满足不视为问题 |
-| SHALL NOT / MUST NOT | 禁止行为 | 必须验证不存在，违规即 FAIL |
-
-### 实现状态判定标准
-- **✅ 满足**: 代码完整实现了规格描述的行为，有通过的测试覆盖
-- **❌ 不满足**: 缺少实现或实现明显不符合规格描述，不满足路径清晰
-- **⚠️ 部分满足**: 主要路径通过但边界条件未覆盖，或实现与规格有细微出入
-
-### 证据
-- 必须提供可验证的证据，不写"代码已实现"这种模糊描述
-- 好的证据：`src/lib/validate.ts:42-58 实现了 isEmail()`、`test/lib/validate.test.ts:15 测试通过"`
-- 可以在备注中附加截图或日志
-
-## 不满足项详情
-
-对于 ❌ 不满足 和 ⚠️ 部分满足 的规格项，在此逐项展开分析。
-
-### {{规格项 ID}}: {{规格项描述}}
-
-- **规格要求**: <!-- 原文引用 -->
-- **实现现状**: <!-- 代码中实际发生了什么 -->
-- **差异分析**: <!-- 为什么有差异 -->
-- **影响评估**: <!-- 影响范围：当前 change 范围 / 全局 / 下游 -->
-- **修复建议**:
-  - <!-- 具体要改的文件、加什么逻辑、改什么测试 -->
-  - <!-- 如 "src/lib/validate.ts: 增加 email 格式校验分支" -->
-
-### <!-- 下一个不满足项 -->
-
-<!-- 无 ❌/⚠️ 项时写"所有规格项均已满足，无不满足项。" -->
-
-## 结论
-
-- [ ] **PASS** — 所有规格项满足，无 ❌ 项
-- [ ] **FAIL** — 存在 ❌ 不满足的规格项：
-  - <!-- 列出具体不满足项的 ID 和简要描述 -->
-
-**审查建议：**
-- PASS 且无 ⚠️ 项 → 可进入下一阶段
-- PASS 但有 ⚠️ 项 → 记录为后续跟踪项（可不阻塞但需记录）
-- FAIL → 阻塞进入 verify，需回 apply 修复后重新审查