gsd-lite 0.1.0

package/workflows/review-cycle.md

@@ -0,0 +1,153 @@
+# 分层审查循环
+
+> 本文档是 reviewer 内联审查策略的扩展指南，按需加载。
+> 冲突时以 `gsd-reviewer.md` 内联规则为准。
+
+---
+
+## 审查级别定义
+
+### L0: 自审即可
+
+**适用范围:** 配置修改、文档更新、CSS 样式、注释变更等无运行时语义变化的任务。
+
+- executor 自审通过 → checkpoint commit = accepted
+- **不启动 reviewer**
+- 判定依据: 纯 docs/comment/style/config 且无运行时语义变化
+
+### L1: 自审 + 阶段批量审查
+
+**适用范围:** 大多数编码任务 (CRUD、UI 组件、工具函数等)。
+
+- executor 自审 → checkpoint commit → 继续执行下一个 task
+- phase 结束时 → 批量派发 reviewer，一次审查该 phase 所有 L1 task
+- 批量审查通过 → 全部 accepted
+- 批量审查发现 Critical → 返工相关 task
+
+### L2: 即时独立审查
+
+**适用范围:** 涉及认证、支付、数据安全、核心架构的关键任务。
+
+- executor 完成 → 立即派发 reviewer (不等 phase 结束)
+- reviewer 独立审查 (不信任 executor 报告)
+- 审查通过 → accepted
+- 审查不通过 → 立即返工
+
+### 判定规则
+
+```
+改 auth/payment/permission/public API/DB migration/core architecture → L2
+纯 docs/comment/style/config 且无运行时语义变化 → L0
+其余 → L1
+拿不准时 → 升一级处理
+```
+
+### 运行时重分类
+
+planner 在计划阶段分配级别，但执行时可能发现实际影响面不同:
+
+- executor 报告 `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
+- executor 标注 `[LEVEL-UP] 建议升级为 L2 因为 ...` → 编排器采纳
+- **不主动降级** — planner 标了 L2 但实际很简单，仍按 L2 审查 (安全优先)
+
+---
+
+## Checkpoint ≠ Accepted 拓扑
+
+```
+L0: checkpoint commit = accepted (自审即可)
+L1: checkpoint commit → [继续执行后续 task] → phase 批量 review → accepted
+L2: checkpoint commit → [等待] → 即时独立 review → accepted
+```
+
+关键区别:
+- **checkpoint** 是 executor 的"我完成了"信号
+- **accepted** 是 reviewer 验证后的"确认合格"信号
+- 下游 task 的依赖门槛 (`gate`) 决定它等待 checkpoint 还是 accepted
+
+---
+
+## 双阶段审查流程
+
+### Stage 1: 规格审查 (Spec Review)
+
+检查代码是否符合任务规格:
+
+- [ ] 所有需求都实现了吗？
+- [ ] 有没有多余的实现 (YAGNI)？
+- [ ] 接口/API 是否符合计划？
+- [ ] 测试是否覆盖了需求中的每个场景？
+
+结果: PASS / FAIL (附具体不符合项 + 代码位置)
+
+### HARD-GATE: 规格审查 → 质量审查
+
+**规格审查必须通过后才能进入质量审查。**
+不要浪费时间优化做错的代码。
+
+### Stage 2: 质量审查 (Quality Review)
+
+(仅在规格审查通过后执行)
+
+检查代码质量:
+
+- [ ] 测试覆盖是否充分？(运行测试 + 检查覆盖率)
+- [ ] 有没有明显的 bug / 安全问题？
+- [ ] 代码是否清晰可维护？
+- [ ] 有无性能问题？
+
+---
+
+## 问题分级
+
+| 级别 | 定义 | 处理方式 |
+|------|------|----------|
+| **Critical** | 安全漏洞 / 数据丢失 / 功能错误 | 必须修复，阻塞 accepted |
+| **Important** | 性能问题 / 可维护性差 | 应该修复，转为后续 task 或记录为 deferred debt |
+| **Minor** | 命名 / 风格 / 代码注释 | 建议修复，不阻塞 accepted |
+
+判定规则:
+- 有 Critical → 返回 FAIL，触发返工
+- 只有 Important/Minor → 返回 PASS + 建议列表
+- Important 必须转成后续 task 或显式记录为 deferred debt
+- Minor 不阻塞，但必须进入 review report
+
+---
+
+## 审查报告模板
+
+```json
+{
+  "scope": "task | phase",
+  "scope_id": "2.3 | phase-2",
+  "review_level": "L2 | L1-batch",
+  "spec_passed": true,
+  "quality_passed": false,
+  "critical_issues": [
+    {
+      "task_id": "2.3",
+      "reason": "描述具体问题",
+      "invalidates_downstream": true
+    }
+  ],
+  "important_issues": [],
+  "minor_issues": [],
+  "accepted_tasks": ["2.1", "2.2"],
+  "rework_tasks": ["2.3"],
+  "evidence": ["ev:test:phase-2", "ev:lint:phase-2"]
+}
+```
+
+---
+
+## 返工流程
+
+1. reviewer 返回 rework_tasks 列表 + 具体原因
+2. 编排器将 rework task 退回 executor，附上审查反馈
+3. executor 修复 → 重新 checkpoint → 重新提交 review
+4. 若返工修改了 contract → 触发下游失效传播 (`needs_revalidation`)
+5. 若返工只改了内部实现 → 下游 task 保持现状，但需重跑验证
+
+**L1 批量审查返工的爆炸半径:**
+- L1 允许 checkpoint 释放下游，batch review 时如发现 Critical，可能导致多个下游 task 连锁 `needs_revalidation`
+- 这是 L1 的已知 trade-off — 缓解方法: planner 对有共享行为依赖的 L1 task 使用 `gate: accepted`

package/workflows/tdd-cycle.md

@@ -0,0 +1,154 @@
+# TDD 循环: RED-GREEN-REFACTOR
+
+> 本文档是 executor 内联 TDD 铁律的扩展指南，按需加载。
+> 冲突时以 `gsd-executor.md` 内联规则为准。
+
+---
+
+## 铁律 (与 executor 一致)
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+唯一例外见下方 §例外列表。
+
+---
+
+## RED: 写失败测试
+
+1. **一次一个行为** — 每个测试只验证一个行为，不合并
+2. **清晰命名** — `should_reject_expired_token` 而非 `test_token_3`
+3. **写真实代码** — 测试调用真实函数/API，不是伪代码占位
+4. **断言具体** — `expect(result.status).toBe(401)` 而非 `expect(result).toBeTruthy()`
+5. **考虑边界** — 写完主路径测试后，立刻考虑: 空值、零值、溢出、并发
+
+### 边界案例策略
+
+对每个行为，系统性检查以下维度:
+
+| 维度 | 常见边界 |
+|------|----------|
+| 空/null | `null`, `undefined`, `""`, `[]`, `{}` |
+| 数值极端 | `0`, `-1`, `Number.MAX_SAFE_INTEGER`, `NaN`, `Infinity` |
+| 字符串 | 空字符串, 超长字符串, 特殊字符, Unicode, SQL 注入模式 |
+| 集合 | 空数组, 单元素, 重复元素, 超大集合 |
+| 时间 | 过期时间, 未来时间, 时区边界, 闰秒 |
+| 并发 | 重复提交, 竞态条件 |
+
+---
+
+## 验证 RED: 观察测试失败
+
+```
+运行测试 → 确认测试失败 → 失败原因符合预期
+```
+
+**强制步骤，不可跳过。** 不验证 RED = 你不知道测试是否真的在测你想测的东西。
+
+检查清单:
+- [ ] 测试运行了 (不是被跳过/过滤掉)
+- [ ] 失败原因是"预期功能不存在"，不是语法错误或配置问题
+- [ ] 如果测试意外通过 → 你的测试写错了，或功能已存在。调查。
+
+---
+
+## GREEN: 最小实现通过
+
+1. **写最少的代码让测试通过** — 不多写一行
+2. **允许"丑陋"的代码** — 这个阶段不追求优雅
+3. **不要提前优化** — 硬编码返回值有时是合法的 GREEN 步骤
+4. **不要偷跑下一个功能** — 只解决当前失败的测试
+
+---
+
+## 验证 GREEN: 观察测试通过
+
+```
+运行全部相关测试 → 新测试通过 → 旧测试不回归
+```
+
+检查清单:
+- [ ] 新测试通过
+- [ ] 已有测试没有因为新代码而失败
+- [ ] 如果测试仍然失败 → 修复实现，不是修改测试
+
+---
+
+## REFACTOR: 保持 GREEN 的前提下清理
+
+1. **提取重复** — 相似代码 → 提取函数/常量
+2. **改善命名** — 实现过程中可能用了临时名称，现在改好
+3. **简化逻辑** — 能用更简单的方式实现吗？
+4. **每次重构后运行测试** — GREEN 不能丢
+
+重构不改行为:
+- 不加新功能 (那是下一个 RED)
+- 不改测试断言 (那说明你在改行为)
+- 不跳过"太小的重构" (小重构积累大质量)
+
+---
+
+## TDD 例外列表 (与 executor 一致)
+
+以下任务不需要先写失败测试:
+
+- 配置文件修改 (`package.json`, `tsconfig`, `.env.example`)
+- CSS / 样式 / 布局变更
+- 数据库迁移脚本 (用迁移工具自身的验证)
+- 纯文档 / 注释 / README
+- CI/CD 配置
+- 环境变量 / 部署配置
+
+这些任务改为: **实现 → 验证生效 → checkpoint commit**
+
+---
+
+## Mock 策略: 何时 Mock vs 真实实现
+
+### 使用 Mock 的场景
+
+| 场景 | 理由 |
+|------|------|
+| 外部 API (支付、邮件、短信) | 不可控、有成本、速度慢 |
+| 数据库 (单元测试层) | 速度 + 隔离 |
+| 时间/随机数 | 确定性 |
+| 文件系统 (危险操作) | 安全 |
+
+### 不要 Mock 的场景
+
+| 场景 | 理由 |
+|------|------|
+| 被测模块自身的逻辑 | Mock 自己 = 测了个寂寞 |
+| 简单的纯函数 | 真实调用更简单也更可靠 |
+| 核心集成路径 | 需要真实行为来验证契约 |
+
+### Mock 原则
+
+- **Mock 边界，不 Mock 内部** — Mock 外部依赖，不 Mock 被测模块内部方法
+- **Mock 应可替换** — 依赖注入 > 猴子补丁
+- **Mock 数量警报** — 一个测试超过 3 个 Mock → 代码耦合太紧，考虑重构
+
+---
+
+## 测试粒度指南
+
+| 层级 | 范围 | 速度 | 占比建议 | 何时写 |
+|------|------|------|----------|--------|
+| 单元 | 单个函数/类 | 毫秒 | 70% | 每个 TDD 循环 |
+| 集成 | 模块间交互 | 秒级 | 20% | API 端点、数据库交互 |
+| E2E | 完整用户流程 | 十秒级 | 10% | 关键路径、冒烟测试 |
+
+原则: **测试金字塔** — 底层多、顶层少。反模式是"冰淇淋蛋筒"(大量 E2E，少量单元)。
+
+---
+
+## 常见合理化及反驳
+
+| 合理化借口 | 为什么是错的 | 正确做法 |
+|------------|--------------|----------|
+| "太简单了不需要测试" | 简单代码也会出错，而且会变复杂 | 写测试。如果真的简单，测试也很快写完 |
+| "我先写完再测试" | 后写的测试立即通过，证明不了任何东西 | 先 RED，再 GREEN |
+| "就这一次跳过" | 你在合理化。下次也会跳过 | 停止。回到正确流程 |
+| "手动测试过了" | 手动 ≠ 可重复验证 | 写自动测试 |
+| "时间不够" | 不写测试 = 以后花更多时间调试 | TDD 实际更快 |
+| "这是原型代码" | 原型代码经常变成生产代码 | 除非确定会丢弃，否则写测试 |
+| "改测试太麻烦" | 脆弱的测试说明设计有问题 | 重构测试 + 重构代码 |