@jahanxu/code-flow 0.2.3 → 0.2.4

package/package.json

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

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

@@ -1,6 +1,6 @@
 # cf-task:archive
 
-归档已完成的整个 task 文件。
+归档已完成的整个 task 文件。归档前执行三维校验，归档后提示更新 specs。
 
 ## 输入
 
@@ -8,7 +8,7 @@
 
 其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
 
-查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 执行步骤
 
@@ -30,9 +30,37 @@
 当前完成度: 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. 提取文件所在的日期目录名（如 `2026-03-15`）
 2. 用 Bash 创建归档目录并移动文件：
@@ -42,7 +70,30 @@
    ```
 3. 如果原日期目录为空，删除空目录
 
-### 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 可自动扫描并补充。
+```
+
+如果无新规范需同步，跳过此步骤。
+
+### 5. 归档摘要
 
 ```
 已归档: <file>.md → .code-flow/tasks/archived/<日期目录>/<file>.md
@@ -53,4 +104,5 @@
   - 创建日期: 2026-03-15
   - 归档日期: 2026-03-20
   - 历时: 5 天
+  - 校验: 3/3 PASS
 ```

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

@@ -8,7 +8,7 @@
 
 其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
 
-查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 执行步骤
 
@@ -19,7 +19,7 @@
    - `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

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

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

@@ -10,7 +10,7 @@
 
 其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
 
-查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 ## 添加批注
 
@@ -20,7 +20,7 @@
 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`
 
@@ -32,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` — 仅输出分析报告，不生成文件
 
 ## 执行步骤
 
@@ -37,6 +38,35 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
 
 此索引用于后续步骤中精确记录每个子任务的来源章节。
 
+### 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. 分析文档，拆解子任务
 
 阅读设计文档内容，按以下原则拆解：
@@ -71,6 +101,12 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
 - **Created**: <当前日期>
 - **Updated**: <当前日期>
 
+## Proposal
+
+<2-3 句话说明变更意图：为什么做这个变更？解决什么问题？期望达成什么效果？>
+
+这段由 AI 从设计文档中提炼生成，帮助编码阶段快速理解全局意图，而不必重读整篇详设。
+
 ---
 
 ## TASK-001: <子任务标题>

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

@@ -9,7 +9,7 @@
 
 其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略日期目录前缀和 `.md` 后缀。
 
-查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，匹配第一个结果。
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，从结果中排除包含 `archived/` 的路径，匹配第一个结果。
 
 示例：
 - `/cf-task:start auth-module TASK-002`
@@ -73,9 +73,10 @@
 
 ### 2. 加载详设文档
 
-读取文件头的 `Source` 字段，用 Read 加载完整的详设文档作为全局上下文。
+1. 读取文件头的 `Source` 字段，提取设计文档路径（文件头 Source 只有路径，无行号范围）
+2. 用 Read 加载完整的详设文档作为全局上下文（不使用 offset/limit）
 
-> 注：整文件模式加载完整详设（因为涉及所有子任务），单任务模式只加载关联章节（节省 token）。
+> 注：整文件模式加载完整详设（因为涉及所有子任务），单任务模式只加载子任务 Source 中引用的章节（节省 token）。
 
 ### 3. 构建执行计划
 

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. 输出总览表格