@michaelxwb/code-flow 0.5.1

package/src/adapters/opencode/commands/cf-task/archive.md

@@ -0,0 +1,135 @@
+---
+description: 归档已完成的 task 文件
+---
+
+# cf-task:archive
+
+归档已完成的整个 task 文件。归档前执行三维校验，归档后提示更新 specs。
+
+## 输入
+
+- `/cf-task:archive <file>` — 归档指定的 task 文件
+
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径。如果匹配到多个结果，输出警告列出所有匹配项，让用户指定完整路径；如果只有一个结果，直接使用。
+
+## 执行步骤
+
+### 1. 完成度检查
+
+1. 用 Read 读取匹配到的 task 文件
+2. 提取所有 `## TASK-xxx` 段落的 Status
+3. 检查是否所有子任务均为 `done`
+
+若有未完成子任务，拒绝归档并输出：
+
+```
+无法归档: 以下子任务未完成
+
+  - TASK-002: in-progress (进度 1/4)
+  - TASK-004: blocked ([BLOCKED] 等待 SDK)
+
+请先完成所有子任务后再归档。
+当前完成度: 2/4 (50%)
+```
+
+### 2. 归档前校验（Verify）
+
+所有子任务 done 后，执行三维校验：
+
+**完整性**：
+- 所有 Checklist 项已勾选
+- 全文无残留的 `#NOTES` 标记
+
+**正确性**：
+- 如果 `.code-flow/validation.yml` 存在，Read 读取验证规则，用 Bash 执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
+- 检查本次变更涉及的文件是否通过 lint/type check
+
+**一致性**：
+- 读取 task 文件的 `## Proposal`，对照实际代码变更，检查意图是否已实现
+
+校验结果输出：
+
+```
+归档前校验:
+  [PASS] 完整性: 所有 Checklist 已完成，无未解决 Notes
+  [PASS] 正确性: cf-validate 通过
+  [WARN] 一致性: Proposal 提到"支持 OAuth 登录"，但未发现相关实现
+
+WARN 不阻塞归档，但建议确认后再继续。继续归档？
+```
+
+PASS → 继续。WARN → 提示用户确认。FAIL → 阻塞归档，列出失败原因。
+
+### 3. 执行归档
+
+校验通过后，先判断布局（任务文件路径形态）：
+
+**A. 需求目录布局**（任务文件位于 `.code-flow/tasks/<日期>/<需求>/<需求>.md`）——**整个需求目录一并归档**：
+```bash
+mkdir -p .code-flow/tasks/archived/<日期>
+mv .code-flow/tasks/<日期>/<需求>/ .code-flow/tasks/archived/<日期>/<需求>/
+```
+目录内的 `.prd.md` / `.frontend.design.md` / `.backend.design.md` / `.design.md` / `.md` 随目录一并归档，无需逐个 mv。
+
+**B. 旧扁平布局**（任务文件直接位于 `.code-flow/tasks/<日期>/<file>.md`，无需求目录，向后兼容）——逐文件归档：
+1. 提取文件所在的日期目录名（如 `2026-03-15`）
+2. 创建归档目录并移动任务文件：
+   ```bash
+   mkdir -p .code-flow/tasks/archived/<日期目录>
+   mv .code-flow/tasks/<日期目录>/<file>.md .code-flow/tasks/archived/<日期目录>/
+   ```
+3. 同名 `.design.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.design.md .code-flow/tasks/archived/<日期目录>/`
+4. 同名 `.prd.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.prd.md .code-flow/tasks/archived/<日期目录>/`
+5. 如果原日期目录为空，删除空目录
+
+**临时约束清理（FEAT-08）**：删除 `.code-flow/specs/_session/task-<name>.md`（存在时）。该文件由 cf-task:start 生成，归档后不得残留。
+
+### 4. Spec 更新提示
+
+归档完成后，检查本次变更是否引入了新的规范约束需要同步到 specs：
+
+1. 读取 task 文件中所有子任务的 Description 和 Checklist
+2. 对照 `.code-flow/specs/` 下的现有规范
+3. 如果发现新增的模式或约束未被 specs 覆盖，提示用户：
+
+```
+Spec 同步建议:
+  本次变更引入了以下尚未记录的规范:
+  - 所有 API handler 增加了 rate limiting 中间件
+  - 新增 AppError 统一错误处理模式
+
+  建议更新:
+  - .code-flow/specs/backend/platform-rules.md — 补充 rate limiting 规则
+  - .code-flow/specs/backend/code-quality-performance.md — 补充错误处理模式
+
+  运行 /cf-learn 可自动扫描并补充。
+```
+
+如果无新规范需同步，跳过此步骤。
+
+### 5. 归档摘要
+
+需求目录布局（A）：
+```
+已归档需求目录: <需求>/ → .code-flow/tasks/archived/<日期>/<需求>/
+  含: <需求>.prd.md、<需求>.frontend.design.md / <需求>.backend.design.md（按实际）、<需求>.md
+```
+
+旧扁平布局（B）：
+```
+已归档: <file>.md → .code-flow/tasks/archived/<日期目录>/<file>.md
+（如有关联设计简报）: <file>.design.md → .code-flow/tasks/archived/<日期目录>/<file>.design.md
+（如有关联 PRD）: <file>.prd.md → .code-flow/tasks/archived/<日期目录>/<file>.prd.md
+```
+
+```
+摘要:
+  - 来源: docs/xxx设计说明书.md
+  - 子任务数: N 个
+  - 创建日期: 2026-03-15
+  - 归档日期: 2026-03-20
+  - 历时: 5 天
+  - 校验: 3/3 PASS
+```

package/src/adapters/opencode/commands/cf-task/block.md

@@ -0,0 +1,34 @@
+---
+description: 标记子任务为阻塞状态
+---
+
+# cf-task:block
+
+标记子任务为阻塞状态。
+
+## 输入
+
+- `/cf-task:block <file> TASK-001 "阻塞原因"`
+
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径。如果匹配到多个结果，输出警告列出所有匹配项，让用户指定完整路径；如果只有一个结果，直接使用。
+
+## 执行步骤
+
+1. 用 Glob 定位任务文件，Read 读取
+2. 定位 `## TASK-001` 段落，检查当前 Status：
+   - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
+   - `blocked` → 提示：`TASK-001 已处于 blocked 状态`，仍追加新的阻塞原因
+   - `draft` / `in-progress` → 继续
+3. 用 Edit 更新 Status 为 `blocked`
+4. 在 `### Log` 前追加：`> BLOCKED: <阻塞原因>`
+5. 在 `### Log` 追加：`- [<当前日期>] blocked (<阻塞原因>, was <原状态>)`
+6. 更新文件头 `Updated` 日期
+7. 输出确认：`TASK-001 已标记为 blocked: <原因>`
+
+## 解除阻塞
+
+阻塞的解除不通过本命令操作，而是：
+- 如果是 Notes 导致的阻塞 → 用 `/project:cf-task:note` 与 AI 讨论解决后自动解除
+- 如果是 `[BLOCKED]` 标记 → 用户手动编辑文件移除 `[BLOCKED]` 条目，或用 `/project:cf-task:start` 重新启动（需所有阻塞条件清除）

package/src/adapters/opencode/commands/cf-task/graph.md

@@ -0,0 +1,77 @@
+---
+description: 可视化子任务依赖关系 DAG
+---
+
+# cf-task:graph
+
+可视化子任务的依赖关系 DAG，识别可并行执行的任务组。
+
+## 输入
+
+- `/cf-task:graph <file>` — 显示指定文件的依赖图
+- `/cf-task:graph` — 显示所有活跃 task 文件的依赖图
+
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径。如果匹配到多个结果，输出警告列出所有匹配项，让用户指定完整路径；如果只有一个结果，直接使用。
+
+## 执行步骤
+
+### 1. 读取任务数据
+
+- 指定文件：Glob 定位后 Read
+- 全部文件：Glob `.code-flow/tasks/**/*.md`，从结果中排除包含 `archived/` 的路径，逐个 Read
+
+从每个 `## TASK-xxx` 段落提取：ID、标题、Status、Depends。
+
+### 2. 构建依赖 DAG
+
+按依赖关系构建有向无环图。检测循环依赖，若存在则报错。
+
+### 3. 输出可视化
+
+用 ASCII art 渲染 DAG，格式示例：
+
+```
+依赖关系图: auth-module
+
+Layer 0 (无依赖):
+  ┌──────────────────────┐   ┌──────────────────────┐
+  │ TASK-001 [draft]     │   │ TASK-003 [draft]     │
+  │ 用户模型定义         │   │ JWT 工具函数         │
+  └──────────┬───────────┘   └──────────┬───────────┘
+             │                          │
+             ▼                          │
+Layer 1:     │                          │
+  ┌──────────┴───────────┐              │
+  │ TASK-002 [draft]     │◄─────────────┘
+  │ 注册接口实现         │
+  └──────────┬───────────┘
+             │
+             ▼
+Layer 2:
+  ┌──────────┴───────────┐
+  │ TASK-004 [draft]     │
+  │ 登录接口实现         │
+  └──────────────────────┘
+
+可并行执行组:
+  - 组 1: TASK-001, TASK-003 (无依赖，可同时开始)
+  - 组 2: TASK-002 (需等待组 1 完成)
+  - 组 3: TASK-004 (需等待组 2 完成)
+
+建议执行顺序: TASK-001 → TASK-003 → TASK-002 → TASK-004
+关键路径: TASK-001 → TASK-002 → TASK-004
+```
+
+### 4. 状态标注
+
+按子任务状态标注：
+- `[draft]` — 待启动
+- `[in-progress]` — 进行中
+- `[done]` — 已完成
+- `[blocked]` — 被阻塞（附原因）
+
+### 5. 多文件模式
+
+当显示所有文件时，按文件分组输出，每个文件一个独立的 DAG。

package/src/adapters/opencode/commands/cf-task/note.md

@@ -0,0 +1,243 @@
+---
+description: 讨论文件中的 #NOTES 标记，对齐最优解后沉淀回原文
+---
+
+# cf-task:note
+
+与用户协作讨论文件中的 `#NOTES` 标记，对齐最优解后将结论沉淀回原文，删除标记。
+
+支持两种文件类型：
+- **任务文件**（`.md`）：讨论任务中的实现细节问题
+- **设计简报**（`.design.md`）：讨论设计方案中的缺陷或待确认项
+
+## 背景
+
+用户在 review 文件时，直接在有问题的位置**就地标注** `#NOTES`，格式：
+
+任务文件中：
+```markdown
+### Checklist
+- [ ] 实现用户注册接口
+- [ ] 密码加密存储  #NOTES 用 bcrypt 还是 argon2？
+- [ ] 编写单元测试
+
+### Description
+实现 JWT 认证  #NOTES token 过期时间设多少合适？
+```
+
+设计简报中：
+```markdown
+## Database Design
+
+### users 表
+| Column | Type | Constraints | Notes |
+|--------|------|-------------|-------|
+| email | VARCHAR(255) | UNIQUE NOT NULL | 登录凭证 #NOTES 需要支持手机号登录吗？ |
+
+## API Design
+
+### POST /auth/register
+- Request: `{ email: string, password: string }`  #NOTES 需要用户名字段吗？
+```
+
+`#NOTES` 是临时讨论标记，解决后必须消失，结论直接融入原文。
+
+## 输入
+
+- `/cf-task:note <file>` — 讨论指定文件中所有 `#NOTES`
+- `/cf-task:note <file> TASK-001` — 只讨论指定子任务中的 `#NOTES`（仅限任务文件）
+
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md` 和 `.code-flow/tasks/**/<file>*.design.md`（`*` 兼容旧 `<file>.design.md` 与域后缀 `<file>.frontend.design.md` / `<file>.backend.design.md`），从结果中排除包含 `archived/` 的路径。如果匹配到多个结果（如全栈需求的前后端 design），输出警告列出所有匹配项，让用户指定要讨论的具体文件；如果只有一个结果，直接使用。
+
+## 执行步骤
+
+### 0. 判断文件类型
+
+Read 读取匹配到的文件后，判断类型：
+- 文件路径以 `.design.md` 结尾 → **设计简报模式**
+- 其他 → **任务文件模式**
+
+---
+
+## 任务文件模式
+
+### 1. 扫描 #NOTES 标记
+
+1. 用 Glob 定位任务文件，Read 读取全文
+2. 用正则扫描所有包含 `#NOTES` 的行，记录：
+   - 所在的子任务（`## TASK-xxx`）
+   - 所在的段落（Description / Checklist / 其他）
+   - 原始行内容
+   - `#NOTES` 后的问题描述
+3. 如果没有找到 `#NOTES`，提示"无待讨论的标记"，结束
+
+输出扫描结果：
+```
+找到 3 个 #NOTES 标记:
+
+TASK-001:
+  1. [Checklist] 密码加密存储  #NOTES 用 bcrypt 还是 argon2？
+  2. [Description] 实现 JWT 认证  #NOTES token 过期时间设多少合适？
+
+TASK-002:
+  3. [Checklist] 调用支付 SDK  #NOTES 用哪个版本的 SDK？
+
+开始逐条讨论...
+```
+
+### 2. 加载上下文
+
+1. 读取当前子任务的 `Source` 字段，解析章节引用
+2. 用 Read 按行号范围读取详设文档的对应章节
+3. 将详设上下文作为讨论背景
+
+### 3. 逐条讨论
+
+对每个 `#NOTES`，展示上下文并给出建议方案，与用户对话：
+
+```
+--- #NOTES 1/3 ---
+位置: TASK-001 / Checklist
+原文: 密码加密存储  #NOTES 用 bcrypt 还是 argon2？
+
+详设参考 (§3.1 L95-L98):
+  "用户密码必须加密存储，推荐使用行业标准算法"
+
+分析:
+  - bcrypt: 成熟稳定，生态支持好，Node.js 原生支持
+  - argon2: 更现代，抗 GPU 攻击更强，但依赖 C 编译
+
+建议: bcrypt（项目技术栈为 Node.js，无需额外编译依赖）
+
+是否采纳？或提出你的方案:
+```
+
+等待用户回应。
+
+### 4. 沉淀结论并清除标记
+
+用户确认方案后：
+
+1. 用 Edit 将该行中的 `#NOTES xxx` 删除，并将结论融入原文
+   - 修改前：`- [ ] 密码加密存储  #NOTES 用 bcrypt 还是 argon2？`
+   - 修改后：`- [ ] 密码使用 bcrypt 加密存储`
+2. 如果结论需要新增步骤 → 用 Edit 追加 Checklist 条目或补充 Description
+3. 在 `### Log` 追加：`- [<当前日期>] resolved #NOTES: <结论摘要>`
+
+**Edit 边界约束（必须遵守）**：
+- `old_string` 必须严格限定在当前 TASK 段落内，**绝对禁止**匹配到 `---` 分隔线或下一个 `## TASK-xxx` 标题
+- Log 追加时，`old_string` 只匹配 Log 段落的最后一行内容，不要向下延伸到段落外
+- 如果 Log 是当前 TASK 的最后一个段落，其内容到 `---` 分隔线之前结束；`old_string` 不得包含 `---` 及其后的任何内容
+- 示例（正确）：`old_string = "- [2026-03-23] created (draft)"` → 只匹配 Log 末行
+- 示例（错误）：`old_string = "- [2026-03-23] created (draft)\n\n---\n\n## TASK-003"` → 越界，会删除下一个 TASK 标题
+
+### 5. 完成检查
+
+所有 `#NOTES` 讨论完毕后：
+
+1. 再次扫描文件，确认无残留 `#NOTES` 标记
+2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`：
+   - 扫描 `### Log`，查找 `blocked` 记录中的原状态
+   - 用 Edit 恢复原状态
+   - 在 `### Log` 追加：`- [<当前日期>] unblocked (all #NOTES resolved, restored to <原状态>)`
+3. 更新文件头 `Updated` 日期
+
+### 6. 输出摘要
+
+```
+#NOTES 讨论完成: auth-module
+
+已解决:
+  1. TASK-001 密码加密 → 使用 bcrypt
+  2. TASK-001 token 过期 → 设为 7 天，支持 refresh
+  3. TASK-002 SDK 版本 → 使用 v3.2.1
+
+文件已更新，所有 #NOTES 标记已清除。
+可执行 /cf-task:start auth-module 开始编码。
+```
+
+---
+
+## 设计简报模式
+
+### 1. 扫描 #NOTES 标记
+
+1. Read 读取 `.design.md` 全文
+2. 用正则扫描所有包含 `#NOTES` 的行，记录：
+   - 所在的章节（`## Goal` / `## Database Design` / `## API Design` 等）
+   - 原始行内容
+   - `#NOTES` 后的问题描述
+3. 如果没有找到 `#NOTES`，提示"无待讨论的标记"，结束
+
+输出扫描结果：
+```
+找到 2 个 #NOTES 标记 (设计简报):
+
+[Database Design]:
+  1. email 字段  #NOTES 需要支持手机号登录吗？
+
+[API Design / POST /auth/register]:
+  2. Request schema  #NOTES 需要用户名字段吗？
+
+开始逐条讨论...
+```
+
+### 2. 加载上下文
+
+设计简报本身就是设计文档，无需加载外部 Source。上下文来自：
+
+1. 读取 `.design.md` 中该 `#NOTES` 所在章节的完整内容
+2. 扫描代码库中与该问题相关的现有实现（如 Glob 搜索现有 model/route/middleware）
+3. 将代码库上下文 + 设计文档上下文作为讨论背景
+
+### 3. 逐条讨论
+
+对每个 `#NOTES`，展示上下文并给出建议方案，与用户对话：
+
+```
+--- #NOTES 1/2 ---
+位置: Database Design / users 表
+原文: email 字段  #NOTES 需要支持手机号登录吗？
+
+当前设计: users 表仅有 email 字段作为登录凭证
+代码库参考: 现有 User model 无手机号字段，mailer 模块仅支持邮件
+
+分析:
+  - 仅邮箱: 与现有 mailer 模块一致，MVP 足够
+  - 支持手机号: 需新增 phone 字段、SMS 服务依赖、双凭证登录逻辑
+
+建议: 仅邮箱（与 Non-goals 中"保持 MVP 精简"一致，手机号可后续迭代）
+
+是否采纳？或提出你的方案:
+```
+
+### 4. 沉淀结论并清除标记
+
+用户确认方案后：
+
+1. 用 Edit 将该行中的 `#NOTES xxx` 删除，并将结论融入原文
+   - 修改前：`| email | VARCHAR(255) | UNIQUE NOT NULL | 登录凭证 #NOTES 需要支持手机号登录吗？ |`
+   - 修改后：`| email | VARCHAR(255) | UNIQUE NOT NULL | 登录凭证（仅邮箱，手机号后续迭代） |`
+2. 如果结论影响其他章节（如 Database Design 的结论影响 API Design），同步更新相关章节
+
+### 5. 完成检查
+
+所有 `#NOTES` 讨论完毕后：
+
+1. 再次扫描文件，确认无残留 `#NOTES` 标记
+2. 无 Log 段落需更新（设计简报没有 Log）
+
+### 6. 输出摘要
+
+```
+#NOTES 讨论完成: user-auth.design.md
+
+已解决:
+  1. [Database Design] 登录凭证 → 仅邮箱，手机号后续迭代
+  2. [API Design] 注册接口 → 不加 username 字段，保持 email + password
+
+文件已更新，所有 #NOTES 标记已清除。
+可执行 /cf-task:plan .code-flow/tasks/2026-04-06/user-auth.design.md 拆解任务。
+```