@jahanxu/code-flow 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahanxu/code-flow",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

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

@@ -1,18 +1,20 @@
 # cf-task:archive
 
-归档已完成的整个 task 文件。
+归档已完成的整个 task 文件。归档前执行三维校验，归档后提示更新 specs。
 
 ## 输入
 
 - `/cf-task:archive <file>` — 归档指定的 task 文件
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 执行步骤
 
 ### 1. 完成度检查
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Read 读取匹配到的 task 文件
 2. 提取所有 `## TASK-xxx` 段落的 Status
 3. 检查是否所有子任务均为 `done`
 
@@ -28,21 +30,73 @@
 当前完成度: 2/4 (50%)
 ```
 
-### 2. 执行归档
+### 2. 归档前校验（Verify）
+
+所有子任务 done 后，执行三维校验：
+
+**完整性**：
+- 所有 Checklist 项已勾选
+- 无未解决的 Notes（无 `[NOTE-n]` 未标记 `[RESOLVED]`）
+
+**正确性**：
+- 如果 `.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. 执行归档
 
-1. 用 Bash 创建归档目录并移动文件：
+校验通过后：
+
+1. 提取文件所在的日期目录名（如 `2026-03-15`）
+2. 用 Bash 创建归档目录并移动文件：
    ```bash
-   mkdir -p .code-flow/tasks/archived
-   mv .code-flow/tasks/<file>.md .code-flow/tasks/archived/
+   mkdir -p .code-flow/tasks/archived/<日期目录>
+   mv .code-flow/tasks/<日期目录>/<file>.md .code-flow/tasks/archived/<日期目录>/
    ```
-2. 输出归档摘要
+3. 如果原日期目录为空，删除空目录
+
+### 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 可自动扫描并补充。
+```
+
+如果无新规范需同步，跳过此步骤。
 
-### 3. 归档摘要
+### 5. 归档摘要
 
 ```
-已归档: <file>.md → .code-flow/tasks/archived/<file>.md
+已归档: <file>.md → .code-flow/tasks/archived/<日期目录>/<file>.md
 
 摘要:
   - 来源: docs/xxx设计说明书.md
@@ -50,4 +104,5 @@
   - 创建日期: 2026-03-15
   - 归档日期: 2026-03-20
   - 历时: 5 天
+  - 校验: 3/3 PASS
 ```

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

@@ -6,18 +6,20 @@
 
 - `/cf-task:block <file> TASK-001 "阻塞原因"`
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 执行步骤
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落，检查当前 Status：
    - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
    - `blocked` → 提示：`TASK-001 已处于 blocked 状态`，仍追加新的阻塞原因
    - `draft` / `in-progress` → 继续
 3. 用 Edit 更新 Status 为 `blocked`
 4. 在 `### Notes` 追加：`- [BLOCKED] <阻塞原因>`
-5. 在 `### Log` 追加：`- [<当前日期>] blocked (<阻塞原因>)`
+5. 在 `### Log` 追加：`- [<当前日期>] blocked (<阻塞原因>, was <原状态>)`
 6. 更新文件头 `Updated` 日期
 7. 输出确认：`TASK-001 已标记为 blocked: <原因>`
 

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

@@ -7,14 +7,16 @@
 - `/cf-task:graph <file>` — 显示指定文件的依赖图
 - `/cf-task:graph` — 显示所有活跃 task 文件的依赖图
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 执行步骤
 
 ### 1. 读取任务数据
 
-- 指定文件：Read `.code-flow/tasks/<file>.md`
-- 全部文件：Glob `.code-flow/tasks/*.md`（排除 `archived/` 目录），逐个 Read
+- 指定文件：Glob 定位后 Read
+- 全部文件：Glob `.code-flow/tasks/**/*.md`，从结果中排除包含 `archived/` 的路径，逐个 Read
 
 从每个 `## TASK-xxx` 段落提取：ID、标题、Status、Depends。
 

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

@@ -8,17 +8,19 @@
 - `/cf-task:note <file> TASK-001 resolve NOTE-1` — 标记批注为已解决
 - `/cf-task:note <file> TASK-001 resolve all` — 标记所有批注为已解决
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 添加批注
 
 ### 执行步骤
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落下的 `### Notes` 区域
 3. 扫描已有 `[NOTE-n]`，计算下一个编号
 4. 用 Edit 在 `### Notes` 下追加：`- [NOTE-<n>] <批注内容>`
-5. 如果子任务 Status 为 `in-progress`，自动用 Edit 改为 `blocked`，并在 `### Log` 追加：`- [<当前日期>] blocked (unresolved note)`
+5. 如果子任务 Status 为 `in-progress` 或 `draft`，自动用 Edit 改为 `blocked`，并在 `### Log` 追加：`- [<当前日期>] blocked (unresolved note, was <原状态>)`（记录阻塞前的状态，用于后续恢复）
 6. 更新文件头 `Updated` 日期
 7. 输出确认：`已添加 [NOTE-<n>]，TASK-001 状态: blocked`
 
@@ -30,8 +32,8 @@
 2. 定位指定的 `[NOTE-n]` 批注
 3. 用 Edit 将 `[NOTE-n]` 改为 `[NOTE-n] [RESOLVED]`
 4. 检查是否还有未解决的 Notes：
-   - 全部解决 + 状态为 blocked → 自动恢复为 `draft`（如果之前是 draft 被阻塞）或 `in-progress`
-   - 在 `### Log` 追加：`- [<当前日期>] unblocked (notes resolved)`
+   - 全部解决 + 状态为 blocked → 扫描 `### Log`，查找最近一条 `blocked (unresolved note, was <状态>)` 记录，恢复为记录中的原状态
+   - 在 `### Log` 追加：`- [<当前日期>] unblocked (notes resolved, restored to <原状态>)`
 5. 更新文件头 `Updated` 日期
 6. 输出确认
 

package/src/adapters/claude/commands/cf-task/plan.md

@@ -6,6 +6,7 @@
 
 - `/cf-task:plan <设计文档路径>` — 指定文档路径
 - `/cf-task:plan` — 交互式选择（从 `docs/` 目录列出候选）
+- `/cf-task:plan <设计文档路径> --explore` — 仅输出分析报告，不生成文件
 
 ## 执行步骤
 
@@ -18,7 +19,55 @@
 2. 展示列表，让用户选择目标文档
 3. Read 读取选中的文档
 
-### 2. 分析文档，拆解子任务
+### 2. 建立章节索引
+
+Read 设计文档后，**先扫描文档结构**，建立章节索引表：
+
+```
+章节索引:
+  §1 概述 (L1-L25)
+  §2 需求分析 (L26-L80)
+    §2.1 用户故事 (L28-L55)
+    §2.2 非功能需求 (L56-L80)
+  §3 详细设计 (L81-L200)
+    §3.1 数据模型 (L83-L110)
+    §3.2 API 接口 (L111-L155)
+    §3.3 业务逻辑 (L156-L200)
+  ...
+```
+
+此索引用于后续步骤中精确记录每个子任务的来源章节。
+
+### 2.5. Explore 模式（--explore）
+
+如果用户传入 `--explore`，在建立章节索引后，输出以下分析报告，**不生成任务文件**：
+
+```
+探索分析报告
+============
+
+文档: docs/xxx设计说明书.md
+章节数: N | 预估子任务数: M
+
+功能域识别:
+  - 用户认证 (§3.1-§3.3) — 核心功能，建议 P0
+  - 支付集成 (§3.4-§3.6) — 依赖第三方 SDK，存在阻塞风险
+  - 通知系统 (§3.7) — 独立模块，可并行
+
+关键依赖:
+  - §3.2 API 接口依赖 §3.1 数据模型
+  - §3.5 支付回调依赖 §3.4 订单模型
+
+风险点:
+  - §3.4 中提到的第三方 SDK 版本未确定
+  - §3.6 缺少错误码定义
+
+建议: 确认风险点后，运行 /cf-task:plan docs/xxx.md 生成任务文件
+```
+
+输出后结束，不进入后续步骤。
+
+### 3. 分析文档，拆解子任务
 
 阅读设计文档内容，按以下原则拆解：
 
@@ -28,12 +77,20 @@
 - 预估编码时间 15-60 分钟
 
 **提取内容**：
-- 功能需求 → 子任务标题 + 描述
+- 功能需求 → 子任务标题 + 描述（提炼重点，不必复制全文）
 - 实现要点 → Checklist 条目
 - 模块依赖 → Depends 字段
 - 紧急程度 → Priority（P0 核心功能 / P1 重要功能 / P2 优化项）
 
-### 3. 生成任务文件方案
+**关键：精确记录章节引用**
+
+每个子任务的 `Source` 字段必须记录该任务对应的详设文档**具体章节和行号范围**。
+
+引用格式：`文件路径#章节标题(L起始-L结束)`，多个章节用逗号分隔。
+
+验证方法：记录引用后，用 Read 工具按行号范围回读验证，确保引用内容与子任务描述一致。如不一致，修正行号。
+
+### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
 
@@ -44,6 +101,12 @@
 - **Created**: <当前日期>
 - **Updated**: <当前日期>
 
+## Proposal
+
+<2-3 句话说明变更意图：为什么做这个变更？解决什么问题？期望达成什么效果？>
+
+这段由 AI 从设计文档中提炼生成，帮助编码阶段快速理解全局意图，而不必重读整篇详设。
+
 ---
 
 ## TASK-001: <子任务标题>
@@ -51,9 +114,10 @@
 - **Status**: draft
 - **Priority**: P0
 - **Depends**:
+- **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
 
 ### Description
-<从设计文档提取的需求描述>
+<从设计文档提取的需求重点，不必复制全文>
 
 ### Checklist
 - [ ] <具体实现步骤1>
@@ -68,6 +132,13 @@
 ---
 
 ## TASK-002: <子任务标题>
+
+- **Status**: draft
+- **Priority**: P1
+- **Depends**: TASK-001
+- **Source**: docs/xxx.md#§3.2 API 接口(L111-L155), docs/xxx.md#§3.3 业务逻辑(L156-L180)
+
+### Description
 ...
 ```
 
@@ -77,11 +148,13 @@
 拆解结果（共 N 个子任务）：
 
 TASK-001: <标题> [P0]
+  来源: §3.1 数据模型 (L83-L110)
   描述: ...
   Checklist: N 项
   依赖: 无
 
 TASK-002: <标题> [P1]
+  来源: §3.2 API 接口 (L111-L155), §3.3 业务逻辑 (L156-L180)
   描述: ...
   Checklist: N 项
   依赖: TASK-001
@@ -90,24 +163,26 @@ TASK-002: <标题> [P1]
 - 修改某个子任务的内容
 - 删除不需要的子任务
 - 合并过于细碎的子任务
-- 调整依赖关系
+- 调整依赖关系和章节引用
 ```
 
 等待用户确认或调整。
 
-### 4. 写入文件
+### 5. 写入文件
 
 用户确认后：
-1. 文件名取模块/功能名（kebab-case），如 `auth-module.md`、`payment-api.md`
-2. 用 Write 写入 `.code-flow/tasks/<name>.md`
+1. 文件名取模块/功能名（kebab-case），如 `auth-module.md`
+2. 按当前日期创建目录：`.code-flow/tasks/<YYYY-MM-DD>/`
+3. 用 Write 写入 `.code-flow/tasks/<YYYY-MM-DD>/<name>.md`
 
-### 5. 输出摘要
+### 6. 输出摘要
 
 ```
-已生成任务文件: .code-flow/tasks/<name>.md
+已生成任务文件: .code-flow/tasks/2026-03-15/auth-module.md
 - 子任务数: N
 - P0: x 个, P1: y 个, P2: z 个
 - 依赖链深度: N 层
+- 详设引用覆盖: §3.1, §3.2, §3.3, §3.5 (共 4 个章节)
 
 建议执行顺序:
   1. TASK-001 (无依赖)
@@ -116,7 +191,7 @@ TASK-002: <标题> [P1]
   ...
 
 下一步:
-  - 审阅任务: 直接阅读 .code-flow/tasks/<name>.md
-  - 添加批注: /cf-task:note <name> TASK-001 "批注内容"
-  - 开始编码: /cf-task:start <name>
+  - 审阅任务: 直接阅读 .code-flow/tasks/2026-03-15/auth-module.md
+  - 添加批注: /cf-task:note auth-module TASK-001 "批注内容"
+  - 开始编码: /cf-task:start auth-module
 ```

package/src/adapters/claude/commands/cf-task/start.md

@@ -7,7 +7,9 @@
 - `/cf-task:start <file> TASK-001` — 激活指定文件中的单个子任务
 - `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务
 
-其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 示例：
 - `/cf-task:start auth-module TASK-002`
@@ -17,7 +19,7 @@
 
 ### 1. 前置检查
 
-用 Read 读取 `.code-flow/tasks/<file>.md`，定位 `## TASK-xxx` 段落：
+用 Read 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
 - `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
@@ -33,22 +35,35 @@
 - 所有依赖必须为 `done`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
-### 2. 激活并编码
+### 2. 加载详设上下文
+
+前置检查通过后，**编码前先加载关联的详设文档章节**：
+
+1. 读取子任务的 `Source` 字段，解析章节引用
+   - 格式：`docs/xxx.md#§3.1 数据模型(L83-L110)`
+   - 提取：文件路径 + 行号范围
+2. 用 Read 按行号范围读取详设文档的对应章节（使用 offset/limit 参数）
+3. 将读取的章节内容作为编码上下文，与 Checklist 一起指导实现
+
+示例：Source 为 `docs/auth.md#§3.2 API 接口(L111-L155), docs/auth.md#§3.5 错误码(L201-L220)`
+→ Read `docs/auth.md` offset=111 limit=45
+→ Read `docs/auth.md` offset=201 limit=20
+
+### 3. 激活并编码
 
-前置检查通过后：
 1. 用 Edit 更新子任务 Status 为 `in-progress`
 2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
 3. 更新文件头 `Updated` 日期
-4. 读取 `### Checklist`，逐项执行编码工作
+4. 结合详设上下文 + Checklist，逐项执行编码工作
 5. 每完成一个 checklist 项 → 用 Edit 将 `- [ ]` 改为 `- [x]`
 
-### 3. 自动完成
+### 4. 自动完成
 
 当所有 checklist 项都勾选为 `[x]` 后：
 1. 用 Edit 更新 Status 为 `done`
 2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
 3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成 ✓`
+4. 输出：`TASK-xxx 已完成`
 
 ## 整文件模式
 
@@ -56,7 +71,14 @@
 
 用 Read 读取整个 task 文件，提取所有 `## TASK-xxx` 段落的 ID、Status、Depends。
 
-### 2. 构建执行计划
+### 2. 加载详设文档
+
+1. 读取文件头的 `Source` 字段，提取设计文档路径（文件头 Source 只有路径，无行号范围）
+2. 用 Read 加载完整的详设文档作为全局上下文（不使用 offset/limit）
+
+> 注：整文件模式加载完整详设（因为涉及所有子任务），单任务模式只加载子任务 Source 中引用的章节（节省 token）。
+
+### 3. 构建执行计划
 
 按依赖关系拓扑排序：
 1. 筛选所有 `draft` 状态的子任务
@@ -81,13 +103,13 @@
 开始执行...
 ```
 
-### 3. 按序执行
+### 4. 按序执行
 
-对每个可激活的子任务，执行单任务模式的步骤 2-3。
+对每个可激活的子任务，执行单任务模式的步骤 3-4（详设已在步骤 2 加载，无需重复读取）。
 
 完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
 
-### 4. 输出摘要
+### 5. 输出摘要
 
 ```
 执行完成：

package/src/adapters/claude/commands/cf-task/status.md

@@ -11,7 +11,7 @@
 
 ### 1. 读取任务数据
 
-- 用 Glob 搜索 `.code-flow/tasks/*.md`（排除 `archived/` 目录）
+- 用 Glob 搜索 `.code-flow/tasks/**/*.md`，从结果中排除包含 `archived/` 的路径
 - 逐个 Read，提取每个 `## TASK-xxx` 的：ID、标题、Status、Priority、Depends、Checklist 完成度
 
 ### 2. 输出总览表格