specops 0.2.5 → 0.3.2

package/.opencode/templates/verification-report.md

@@ -0,0 +1,322 @@
+# 验证报告模板
+
+`.planning/phases/XX-name/{phase_num}-VERIFICATION.md` 的模板，用于记录阶段目标验证结果。
+
+---
+
+## 文件模板
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M 必要项已验证
+---
+
+# 阶段 {X}: {Name} 验证报告
+
+**阶段目标:** {ROADMAP.md 中的目标}
+**验证时间:** {timestamp}
+**状态:** {passed | gaps_found | human_needed}
+
+## 目标达成情况
+
+### 可观测事实
+
+| # | 事实 | 状态 | 证据 |
+|---|------|------|------|
+| 1 | {must_haves 中的事实} | ✓ 已验证 | {确认依据} |
+| 2 | {must_haves 中的事实} | ✗ 失败 | {问题描述} |
+| 3 | {must_haves 中的事实} | ? 不确定 | {无法验证的原因} |
+
+**得分:** {N}/{M} 项事实已验证
+
+### 必需产物
+
+| 产物 | 预期 | 状态 | 详情 |
+|------|------|------|------|
+| `src/components/Chat.tsx` | 消息列表组件 | ✓ 存在且有实质内容 | 导出 ChatList，渲染 Message[]，无桩代码 |
+| `src/app/api/chat/route.ts` | 消息 CRUD | ✗ 桩代码 | 文件存在但 POST 返回占位内容 |
+| `prisma/schema.prisma` | Message 模型 | ✓ 存在且有实质内容 | 模型已定义所有字段 |
+
+**产物:** {N}/{M} 已验证
+
+### 关键连接验证
+
+| 来源 | 目标 | 通过 | 状态 | 详情 |
+|------|------|------|------|------|
+| Chat.tsx | /api/chat | useEffect 中的 fetch | ✓ 已连接 | 第 23 行: `fetch('/api/chat')` 含响应处理 |
+| ChatInput | /api/chat POST | onSubmit 处理器 | ✗ 未连接 | onSubmit 只调用了 console.log |
+| /api/chat POST | 数据库 | prisma.message.create | ✗ 未连接 | 返回硬编码响应，无数据库调用 |
+
+**连接:** {N}/{M} 已验证
+
+## 需求覆盖
+
+| 需求 | 状态 | 阻塞问题 |
+|------|------|----------|
+| {REQ-01}: {描述} | ✓ 已满足 | - |
+| {REQ-02}: {描述} | ✗ 被阻塞 | API 路由是桩代码 |
+| {REQ-03}: {描述} | ? 需人工 | 无法通过程序验证 WebSocket |
+
+**覆盖率:** {N}/{M} 需求已满足
+
+## 发现的反模式
+
+| 文件 | 行号 | 模式 | 严重程度 | 影响 |
+|------|------|------|----------|------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ 警告 | 表明未完成 |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 阻塞 | 无实际内容渲染 |
+| src/hooks/useChat.ts | - | 文件缺失 | 🛑 阻塞 | 预期的 hook 不存在 |
+
+**反模式:** {N} 个 ({blockers} 个阻塞, {warnings} 个警告)
+
+## 需要人工验证
+
+{如果不需要人工验证:}
+无需人工验证，所有可验证项已通过程序检查。
+
+{如果需要人工验证:}
+
+### 1. {测试名称}
+**测试:** {操作步骤}
+**预期:** {应该发生什么}
+**为何需人工:** {为什么无法通过程序验证}
+
+### 2. {测试名称}
+**测试:** {操作步骤}
+**预期:** {应该发生什么}
+**为何需人工:** {为什么无法通过程序验证}
+
+## 缺口总结
+
+{如果没有缺口:}
+**未发现缺口。** 阶段目标已达成，可以继续推进。
+
+{如果发现缺口:}
+
+### 关键缺口（阻塞进度）
+
+1. **{缺口名称}**
+   - 缺失: {缺少什么}
+   - 影响: {为什么阻塞目标}
+   - 修复: {需要做什么}
+
+2. **{缺口名称}**
+   - 缺失: {缺少什么}
+   - 影响: {为什么阻塞目标}
+   - 修复: {需要做什么}
+
+### 非关键缺口（可延后）
+
+1. **{缺口名称}**
+   - 问题: {什么问题}
+   - 影响: {影响有限，因为...}
+   - 建议: {现在修复还是延后}
+
+## 建议修复计划
+
+{如果发现缺口，生成修复计划建议:}
+
+### {phase}-{next}-PLAN.md: {修复名称}
+
+**目标:** {修复什么}
+
+**任务:**
+1. {修复缺口 1 的任务}
+2. {修复缺口 2 的任务}
+3. {验证任务}
+
+**预估范围:** {小 / 中}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {修复名称}
+
+**目标:** {修复什么}
+
+**任务:**
+1. {任务}
+2. {任务}
+
+**预估范围:** {小 / 中}
+
+---
+
+## 验证元数据
+
+**验证方法:** 目标反推（从阶段目标推导）
+**必要项来源:** {PLAN.md frontmatter | 从 ROADMAP.md 目标推导}
+**自动检查:** {N} 通过, {M} 失败
+**需人工检查:** {N}
+**总验证时间:** {duration}
+
+---
+*验证时间: {timestamp}*
+*验证者: Claude (子代理)*
+```
+
+---
+
+## 指南
+
+**状态值:**
+- `passed` — 所有必要项已验证，无阻塞
+- `gaps_found` — 发现一个或多个关键缺口
+- `human_needed` — 自动检查通过但需要人工验证
+
+**证据类型:**
+- 存在性: "文件在路径，导出 X"
+- 实质性: "N 行代码，包含模式 X, Y, Z"
+- 连接性: "第 N 行: 连接 A 到 B 的代码"
+- 失败: "缺失因为 X" 或 "桩代码因为 Y"
+
+**严重程度:**
+- 🛑 阻塞: 阻止目标达成，必须修复
+- ⚠️ 警告: 表明未完成但不阻塞
+- ℹ️ 信息: 值得注意但无问题
+
+**修复计划生成:**
+- 仅在 gaps_found 时生成
+- 将相关修复归入单个计划
+- 每个计划保持 2-3 个任务
+- 每个计划包含验证任务
+
+---
+
+## 示例
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 必要项已验证
+---
+
+# 阶段 3: 聊天界面 验证报告
+
+**阶段目标:** 可用的聊天界面，用户可以发送和接收消息
+**验证时间:** 2025-01-15T14:30:00Z
+**状态:** gaps_found
+
+## 目标达成情况
+
+### 可观测事实
+
+| # | 事实 | 状态 | 证据 |
+|---|------|------|------|
+| 1 | 用户可以看到已有消息 | ✗ 失败 | 组件渲染占位内容，非消息数据 |
+| 2 | 用户可以输入消息 | ✓ 已验证 | 输入框存在且有 onChange 处理器 |
+| 3 | 用户可以发送消息 | ✗ 失败 | onSubmit 处理器只有 console.log |
+| 4 | 发送的消息出现在列表中 | ✗ 失败 | 发送后无状态更新 |
+| 5 | 消息在刷新后持久化 | ? 不确定 | 无法验证，发送功能不工作 |
+
+**得分:** 1/5 项事实已验证
+
+### 必需产物
+
+| 产物 | 预期 | 状态 | 详情 |
+|------|------|------|------|
+| `src/components/Chat.tsx` | 消息列表组件 | ✗ 桩代码 | 返回 `<div>Chat will be here</div>` |
+| `src/components/ChatInput.tsx` | 消息输入 | ✓ 存在且有实质内容 | 表单含输入框、提交按钮、处理器 |
+| `src/app/api/chat/route.ts` | 消息 CRUD | ✗ 桩代码 | GET 返回 [], POST 返回 { ok: true } |
+| `prisma/schema.prisma` | Message 模型 | ✓ 存在且有实质内容 | Message 模型含 id, content, userId, createdAt |
+
+**产物:** 2/4 已验证
+
+### 关键连接验证
+
+| 来源 | 目标 | 通过 | 状态 | 详情 |
+|------|------|------|------|------|
+| Chat.tsx | /api/chat GET | fetch | ✗ 未连接 | 组件中无 fetch 调用 |
+| ChatInput | /api/chat POST | onSubmit | ✗ 未连接 | 处理器只记录日志，不发请求 |
+| /api/chat GET | 数据库 | prisma.message.findMany | ✗ 未连接 | 返回硬编码 [] |
+| /api/chat POST | 数据库 | prisma.message.create | ✗ 未连接 | 返回 { ok: true }，无数据库调用 |
+
+**连接:** 0/4 已验证
+
+## 需求覆盖
+
+| 需求 | 状态 | 阻塞问题 |
+|------|------|----------|
+| CHAT-01: 用户可以发送消息 | ✗ 被阻塞 | API POST 是桩代码 |
+| CHAT-02: 用户可以查看消息 | ✗ 被阻塞 | 组件是占位内容 |
+| CHAT-03: 消息持久化 | ✗ 被阻塞 | 无数据库集成 |
+
+**覆盖率:** 0/3 需求已满足
+
+## 发现的反模式
+
+| 文件 | 行号 | 模式 | 严重程度 | 影响 |
+|------|------|------|----------|------|
+| src/components/Chat.tsx | 8 | `<div>Chat will be here</div>` | 🛑 阻塞 | 无实际内容 |
+| src/app/api/chat/route.ts | 5 | `return Response.json([])` | 🛑 阻塞 | 硬编码空数组 |
+| src/app/api/chat/route.ts | 12 | `// TODO: save to database` | ⚠️ 警告 | 未完成 |
+
+**反模式:** 3 个 (2 个阻塞, 1 个警告)
+
+## 需要人工验证
+
+自动缺口修复前无需人工验证。
+
+## 缺口总结
+
+### 关键缺口（阻塞进度）
+
+1. **聊天组件是占位内容**
+   - 缺失: 实际的消息列表渲染
+   - 影响: 用户看到 "Chat will be here" 而非消息
+   - 修复: 实现 Chat.tsx 以获取和渲染消息
+
+2. **API 路由是桩代码**
+   - 缺失: GET 和 POST 的数据库集成
+   - 影响: 无数据持久化，无实际功能
+   - 修复: 在路由处理器中接入 prisma 调用
+
+3. **前后端未连接**
+   - 缺失: 组件中的 fetch 调用
+   - 影响: 即使 API 正常，UI 也不会调用它
+   - 修复: 在 Chat 中添加 useEffect fetch，在 ChatInput 中添加 onSubmit fetch
+
+## 建议修复计划
+
+### 03-04-PLAN.md: 实现聊天 API
+
+**目标:** 将 API 路由连接到数据库
+
+**任务:**
+1. 用 prisma.message.findMany 实现 GET /api/chat
+2. 用 prisma.message.create 实现 POST /api/chat
+3. 验证: API 返回真实数据，POST 创建记录
+
+**预估范围:** 小
+
+---
+
+### 03-05-PLAN.md: 实现聊天 UI
+
+**目标:** 将 Chat 组件连接到 API
+
+**任务:**
+1. 用 useEffect fetch 和消息渲染实现 Chat.tsx
+2. 将 ChatInput 的 onSubmit 连接到 POST /api/chat
+3. 验证: 消息正常显示，发送后新消息出现
+
+**预估范围:** 小
+
+---
+
+## 验证元数据
+
+**验证方法:** 目标反推（从阶段目标推导）
+**必要项来源:** 03-01-PLAN.md frontmatter
+**自动检查:** 2 通过, 8 失败
+**需人工检查:** 0 (被自动检查失败阻塞)
+**总验证时间:** 2 分钟
+
+---
+*验证时间: 2025-01-15T14:30:00Z*
+*验证者: Claude (子代理)*
+```

package/.opencode/workflows/add-phase.md

@@ -0,0 +1,111 @@
+<purpose>
+在当前里程碑的路线图末尾添加一个新的整数阶段。自动计算下一个阶段编号，创建阶段目录，并更新路线图结构。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+解析命令参数：
+- 所有参数组成阶段描述
+- 示例：`/specops:add-phase Add authentication` → description = "Add authentication"
+- 示例：`/specops:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+如果未提供参数：
+
+```
+ERROR: Phase description required
+Usage: /specops:add-phase <description>
+Example: /specops:add-phase Add authentication system
+```
+
+退出。
+</step>
+
+<step name="init_context">
+加载阶段操作上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "0")
+```
+
+检查 init JSON 中的 `roadmap_exists`。如果为 false：
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /specops:new-project to initialize.
+```
+退出。
+</step>
+
+<step name="add_phase">
+**将阶段添加操作委托给 specops-tools：**
+
+```bash
+RESULT=$(node .opencode/bin/specops-tools.cjs phase add "${description}")
+```
+
+CLI 处理以下操作：
+- 查找最大的现有整数阶段编号
+- 计算下一个阶段编号（最大值 + 1）
+- 从描述生成 slug
+- 创建阶段目录（`.planning/phases/{NN}-{slug}/`）
+- 在 ROADMAP.md 中插入阶段条目，包含 Goal、Depends on 和 Plans 部分
+
+从结果中提取：`phase_number`、`padded`、`name`、`slug`、`directory`。
+</step>
+
+<step name="update_project_state">
+更新 STATE.md 以反映新阶段：
+
+1. 读取 `.planning/STATE.md`
+2. 在 "## Accumulated Context" → "### Roadmap Evolution" 下添加条目：
+   ```
+   - Phase {N} added: {description}
+   ```
+
+如果 "Roadmap Evolution" 部分不存在，则创建它。
+</step>
+
+<step name="completion">
+展示完成摘要：
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: .planning/ROADMAP.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/specops:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/specops:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `specops-tools phase add` 执行成功
+- [ ] 阶段目录已创建
+- [ ] 路线图已更新，包含新阶段条目
+- [ ] STATE.md 已更新路线图演进记录
+- [ ] 用户已被告知后续步骤
+</success_criteria>