diff --git a/docs/superpowers/specs/2026-06-25-workflow-effort-engine-design.md b/docs/superpowers/specs/2026-06-25-workflow-effort-engine-design.md
new file mode 100644
index 0000000..50ff515
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-25-workflow-effort-engine-design.md
@@ -0,0 +1,207 @@
+# Workflow and Effort Engine Design
+
+## 背景
+
+AI 拆解、开发任务、测试用例和 Bug 当前已经共享了几个核心问题：
+
+- 状态流转分散在组件和 Zustand store 中，容易出现点一条却影响一组的误操作。
+- AI 拆解生成的开发任务可能被自动开始逻辑推进到“开发中”，但实际开始时间应该来自人员手动点击。
+- 测试用例有 `startedAt/completedAt`，但缺少统一的预估时间、实际时间和加权进度展示。
+- AI 估时偏宽，未按“团队使用 AI 辅助开发/测试”的效率口径收敛。
+
+本设计采用轻量规则引擎方案，不引入状态机库。
+
+## 目标
+
+1. 开发任务、测试用例、Bug 的状态操作只允许单条操作。
+2. 实际开始/完成时间只能由对应人员的单条状态流转写入。
+3. 开发任务和测试用例都支持预估时间、实际时间、汇总进度和单条展示。
+4. AI 拆解生成草稿默认停留在待处理状态，不自动进入执行中。
+5. AI 估时使用明确的规则口径，按 AI 辅助研发场景收紧。
+
+## 非目标
+
+- 本阶段不引入 XState 等完整状态机库。
+- 本阶段不做完整后端关系表拆分，仍兼容当前 AppData JSONB 持久化。
+- 本阶段不做任务自动排期，只处理预估/实际耗时与状态流转。
+- Bug 暂不加入预估工时体系，仅先保证单条状态操作和现有实际耗时口径不被批量误触发。
+
+## 推荐方案
+
+使用纯函数规则层：
+
+- `dev-task-workflow.ts`
+- `test-case-workflow.ts`
+- `bug-workflow.ts`
+- `work-effort-engine.ts`
+- `ai-estimation-policy.ts`
+
+组件只发起“单条命令”，store 只负责保存状态，规则判断、时间戳写入和估时计算都放到规则层。
+
+## 开发任务规则
+
+状态机：
+
+```text
+todo -> in_progress -> testing -> submitted
+testing -> in_progress
+submitted 终态
+```
+
+显示文案：
+
+- `todo`: 待开发
+- `in_progress`: 开发中
+- `testing`: 自测
+- `submitted`: 已提测
+
+时间戳规则：
+
+- AI 或人工新建任务默认 `status=todo`。
+- 新建任务不得写入 `actualStartAt/actualEndAt`。
+- 只有单条任务从 `todo` 流转到 `in_progress` 时，才写入 `actualStartAt`。
+- 只有单条任务流转到 `submitted` 时，才写入 `actualEndAt`。
+- DevTask 不再根据预计开始时间自动进入 `in_progress`。
+
+估时规则：
+
+- 新增 `estimateHours?: number` 作为标准预估字段。
+- 旧数据兼容：若没有 `estimateHours`，仍可从 `expectedStartAt/expectedEndAt` 推导。
+- 实际耗时继续由 `actualStartAt -> actualEndAt/currentTime` 计算。
+
+## 测试用例规则
+
+状态机：
+
+```text
+pending -> running -> passed
+pending -> running -> failed
+pending -> running -> blocked
+passed/failed/blocked -> running
+```
+
+显示文案调整：
+
+- `pending`: 待测试
+- `running`: 测试中
+- `passed`: 通过
+- `failed`: 不通过
+- `blocked`: 阻塞
+
+时间戳规则：
+
+- 新建测试用例默认 `status=pending`。
+- 只有单条用例从 `pending` 流转到 `running` 时，才写入 `startedAt`。
+- 只有单条用例流转到 `passed/failed/blocked` 时，才写入 `completedAt`。
+- 回退到 `running` 时，清除 `completedAt/failReason/blockReason`，保留首次 `startedAt`。
+
+估时规则：
+
+- 新增 `estimateHours?: number`。
+- 单条展示 `实际 / 预估`。
+- 汇总展示测试用例总预估、总实际、完成进度和通过率。
+- 完成进度按预估工时加权：`passed/failed/blocked = 100%`，`running = 50%`，`pending = 0%`。
+- 通过率仍只在 `passed/failed` 中计算，不把 `blocked` 计入通过率分母。
+
+## Bug 规则
+
+状态机保持：
+
+```text
+open -> fixing -> fixed -> verifying -> closed
+open -> rejected
+verifying -> open
+```
+
+本阶段只做两点：
+
+- 移除或禁用任何批量通过/批量不通过/批量关闭入口。
+- 任何 Bug 状态按钮只作用于当前单条 Bug。
+
+## 批量操作约束
+
+所有列表、分组、需求维度、版本维度都不得提供隐式批量状态流转。
+
+禁止：
+
+- 点击需求“已提测”后，把需求下全部开发任务提测。
+- 点击测试用例“通过”后，把当前需求/版本下全部用例通过。
+- 点击“不通过”后，把一组用例全部置为失败。
+
+允许：
+
+- 统计和筛选按需求/版本聚合展示。
+- 单条任务、单条测试用例、单条 Bug 的状态按钮。
+
+## AI 估时策略
+
+AI 输出仍保留 `estimateHours`，但必须遵守更严格的区间。
+
+默认按“有 AI 辅助开发/测试”的团队效率估算：
+
+| 类型 | 默认估时 |
+| --- | --- |
+| 简单前端字段/文案/展示调整 | 0.25h - 0.5h |
+| 简单前端交互，如拖拽排序 UI、开关、筛选项 | 0.5h - 1h |
+| 拖拽排序并需要持久化接口 | 1h - 1.5h |
+| 简单 CRUD 接口 | 0.75h - 1.5h |
+| 小型数据库字段/索引调整 | 0.5h |
+| 中等业务规则变更 | 1.5h - 3h |
+| 简单功能测试用例执行 | 0.25h - 0.5h |
+| API/异常/兼容性测试用例执行 | 0.5h - 1h |
+
+只有出现跨端同步、复杂权限、历史数据迁移、强一致性、批量任务、复杂兼容性时，才允许超过默认区间。
+
+## 数据修正
+
+需要兼容已有数据：
+
+- AI 草稿若 `aiDraft=true` 且状态已经是 `in_progress`，并且没有明确人工流转记录，则重置为 `todo` 并清理 `actualStartAt/actualEndAt`。
+- 已有测试用例缺少 `estimateHours` 时，默认补 `0.5h`。
+- 已有开发任务缺少 `estimateHours` 时，从旧的预计时间窗口推导；推导不到则使用 `1h`。
+
+## UI 调整
+
+开发任务：
+
+- AI 草稿进入列表时显示“待开发”。
+- 单条任务详情中保留状态按钮。
+- 需求维度不再提供“全部提测”。
+
+测试用例：
+
+- 列表显示待测试/测试中/通过/不通过/阻塞。
+- 单条用例显示预估、实际、时间范围。
+- 总览显示预估合计、实际合计、完成进度、通过率。
+- 不再提供任何批量通过/不通过。
+
+Bug：
+
+- 只保留单条 Bug 状态按钮。
+
+## 测试策略
+
+单元测试：
+
+- DevTask 状态机合法/非法流转。
+- DevTask 时间戳写入点。
+- TestCase 状态机合法/非法流转。
+- TestCase 时间戳写入点。
+- Work effort 聚合。
+- AI 估时策略边界。
+
+集成级验证：
+
+- AI 拆解采纳后，开发任务为待开发，测试用例为待测试。
+- 点击一条开发任务提测，只影响这一条。
+- 点击一条测试用例通过/不通过，只影响这一条。
+- 页面总览的预估/实际/进度与单条数据一致。
+
+## 实施顺序建议
+
+1. 新增 workflow/effort/estimation 规则层和单元测试。
+2. 改 DevTask 创建、AI 采纳、状态流转和自动开始逻辑。
+3. 给 TestCase 增加 `estimateHours`，统一时间和进度计算。
+4. 移除开发任务、测试用例、Bug 的批量状态入口。
+5. 更新 AI prompt/schema 的估时要求。
+6. 跑类型检查、单元测试和手工页面验证。