@michaelxwb/code-flow 0.6.2 → 0.6.4

package/README.md

@@ -124,8 +124,8 @@ CLAUDE.md                         # 与 Claude 共用全局指令
 
 # OpenCode (--platform=opencode)
 .opencode/commands/               # 命令模板（含 cf-task/）
-.opencode/plugins/code-flow/      # 插件：转发到 cf_user_prompt_hook.py
-opencode.json                     # 插件注册
+.opencode/plugins/code-flow/      # v2 插件：session.prompt 转发到 cf_user_prompt_hook.py
+opencode.json                     # OpenCode 配置（`.opencode/plugins/` 自动发现，无需注册键）
 AGENTS.md                         # 全局指令
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

package/src/adapters/claude/commands/cf-init.md

@@ -64,6 +64,7 @@
 - Python 后端项目：删除 `TypeScript 类型检查`、`Vue 类型检查`、`ESLint`、`Stylelint`、`前端单元测试`
 - Go/Rust/Java 后端：删除前端 validator；如果没有对应语言 validator，保留文件并在摘要中提示用户补充
 - fullstack / generic：全部保留，除非项目明确没有对应语言文件
+- 全量测试 / e2e 等慢命令（`pytest`、`vitest run`、Playwright 等）标 `heavy: true`：Stop 每轮跳过，任务 finish 自动执行一次，也可 `/cf-validate` 手动执行
 
 若 `.code-flow/validation.yml` 缺失，提示用户重跑 `code-flow init`，不要手工拼装 YAML。
 

package/src/adapters/claude/commands/cf-spec.md

@@ -43,7 +43,7 @@
 
 `python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
 
-- marker 漂移时输出下一步（cf-spec doctor resync）。
+- marker 漂移时输出下一步：先 refresh 自动重同步；仍不一致时用 `active doctor --resync`（hash 取 status --json 的 context_sha256）。
 - 需要机器可读输出时加 `--json`。
 
 ## refresh
@@ -59,5 +59,9 @@
 ## doctor
 
 1. 校验 config schema、active marker、lock、Context hash、task/status、migration journal 和 legacy residue。
-2. active marker 存在时执行 `cf_spec_context.py active doctor`，传入可证明的 Context hash；无法证明时保持 `recovery_required`。
-3. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。
+2. 按场景恢复，禁止删除 marker、手改状态或越过 required Gate：
+   - **Context hash drift**（`status` 显示 marker hash 漂移）：先执行 refresh，它会自动重同步 marker hash；成功后继续原流程，不要用 doctor。
+   - **marker 停在 `activating`（start 事务中断）**：取 `status --json` 的 `context_sha256` 执行 `active doctor`；hash/head 可证明时自动恢复 active，无法证明时加 `--resync` 重新绑定。
+   - **marker 损坏或归属无法证明**：向用户说明影响，仅在用户明确确认放弃该 TASK 后执行 `active doctor --abandon`，随后重新规划该任务。
+3. `active doctor` 返回 `recovery_required`（退出码 3）是诊断结果而非崩溃：按第 2 步选择 refresh / `--resync` / `--abandon`，不要用 `--help` 探测或反复重试。
+4. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。

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

@@ -16,7 +16,7 @@
 
 1. 用 Read 读取匹配到的 task 文件
 2. 提取所有 `## TASK-xxx` 段落的 Status
-3. 检查是否所有子任务均为 `done`
+3. 检查是否所有子任务均为 `verified`（E2E 终验后的终态；仍为 `done` 说明 verify-e2e 尚未执行，先跑它）
 
 若有未完成子任务，拒绝归档并输出：
 
@@ -36,24 +36,24 @@
 
 - 需求目录必须存在 `spec-context.yml`；执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`
 - 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage code --json`；required Rule 的 stale/pending/conflict/unverified 任一存在即 FAIL
-- 若 `.code-flow/.active-task.json` 仍指向本需求，必须先完成对应 TASK 的 Done Gate，并以 `{"gate_passed": true}` 调用 `active complete`；不得通过归档绕过 active 状态
+- 若 `.code-flow/.active-task.json` 仍指向本需求，先执行 `python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`，通过后再 verify-e2e；不得自报 gate_passed 或通过归档绕过 active 状态
 - Context 与 Evidence 随需求目录一并归档，`_session` 仅是可重建投影，不是事实源
 
-所有子任务 done 后，执行四维校验：
+所有子任务 verified 后，执行四维校验：
 
 **完整性**：
 - 所有 Checklist 项已勾选
 - 全文无残留的 `#NOTES` 标记
 
 **正确性**：
-- 如果 `.code-flow/validation.yml` 存在，Read 读取验证规则，用 Bash 执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
+- 执行 `python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json`；归档时任务已无 marker，须补充本需求基线至当前的变更路径作为 `--files` 参数，不能把工作区干净误认为本需求无需验证
 - 检查本次变更涉及的文件是否通过 lint/type check
 
 **验收追溯**：
 - 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
 - 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
 - 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
-- 汇总并重新执行契约中所有唯一验收命令；测试未收集、未执行或失败均为 FAIL
+- 先用 `cf_acceptance_manifest.py --task-file "<任务文件>" --output "<需求目录>/.acceptance-manifest.json" --verify-plan` 校验基线，再用 `cf_acceptance_runner.py --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --include-e2e --write-evidence` 统一复验。相同 argv、cwd、timeout 的命令在单次运行内复用结果；跨运行不复用，依赖步骤不跨状态屏障复用。测试未收集、未执行或失败均为 FAIL
 - `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
 
 **一致性**：

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

@@ -14,17 +14,23 @@
 
 1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落，检查当前 Status：
-   - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
+   - `done` / `verified` → 拒绝：`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: <原因>`
+3. 调用统一 workflow service 入口（与 active block 同一状态机），不要先编辑状态或 marker：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py block --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --reason "<阻塞原因>" --json
+```
+
+命令同时更新 Status、阻塞原因、Log、Updated 和匹配的 marker；无 marker 的 draft 任务只改变任务文档。仅在返回成功后确认阻塞；其他需求的 marker 不得改动。
 
 ## 解除阻塞
 
-阻塞的解除不通过本命令操作，而是：
-- 如果是 Notes 导致的阻塞 → 用 `/project:cf-task:note` 与 AI 讨论解决后自动解除
-- 如果是 `[BLOCKED]` 标记 → 用户手动编辑文件移除 `[BLOCKED]` 条目，或用 `/project:cf-task:start` 重新启动（需所有阻塞条件清除）
+先解决 Notes 或外部依赖，再执行：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+resume 会检查未解决的 #NOTES 和依赖，原子同步任务与 marker。未激活的 blocked 任务恢复 draft；已有匹配 marker 的任务恢复 in-progress。失败时保留阻塞状态，不通过手动改 Status 绕过。

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

@@ -13,6 +13,12 @@
 
 ## 执行步骤
 
+### 0. 程序计算（推荐）
+
+用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK；批次内的独立任务由 cf-task:start 在各自 worktree 中并行派发子 agent（预检失败自动回退串行），详见 cf-task:start 步骤 4。
+
+`batches` 是组内可独立开发的拓扑批次；`dependency_components` 是依赖连通分组，只保证组与组之间独立，组内仍有先后依赖。`independent_groups` 仅为后者的兼容别名，不要把它显示成组内并行。
+
 ### 1. 读取任务数据
 
 - 指定文件：Glob 定位后 Read
@@ -65,7 +71,8 @@ Layer 2:
 按子任务状态标注：
 - `[draft]` — 待启动
 - `[in-progress]` — 进行中
-- `[done]` — 已完成
+- `[done]` — 实现完成，E2E 可能仍待终验
+- `[verified]` — 终验完成
 - `[blocked]` — 被阻塞（附原因）
 
 ### 5. 多文件模式

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

@@ -134,10 +134,7 @@ TASK-002:
 所有 `#NOTES` 讨论完毕后：
 
 1. 再次扫描文件，确认无残留 `#NOTES` 标记
-2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`：
-   - 扫描 `### Log`，查找 `blocked` 记录中的原状态
-   - 用 Edit 恢复原状态
-   - 在 `### Log` 追加：`- [<当前日期>] unblocked (all #NOTES resolved, restored to <原状态>)`
+2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`，清除当前阻塞条目后调用 `python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`。命令检查依赖和残留 Notes，同步 marker 与任务状态；不得从历史 Log 猜测状态后只改 Markdown。失败保留 blocked 并报告原因。
 3. 更新文件头 `Updated` 日期
 
 ### 6. 输出摘要

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

@@ -238,7 +238,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 ### Checklist
 - [ ] <具体实现步骤1>
 - [ ] <具体实现步骤2>
-- [ ] [S-01][E2E] 修改生产代码前，按 API → Store → Renderer 真实边界编写验收测试并记录 RED
+- [ ] [S-01][E2E] 编写 E2E 验收测试并登记可单独执行的命令（真实边界：API → Store → Renderer）；不在编码期执行 RED/GREEN，统一留给 verify-e2e
 - [ ] [S-01] 断言 <最终可观测结果 1> 与 <最终可观测结果 2>
 - [ ] [E-01][integration] 覆盖 <异常输入> 与 <可观测失败行为>
 - [ ] 运行验收命令并填写 Acceptance Evidence
@@ -252,7 +252,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 ### Acceptance Evidence
 
-> `cf-task-start` 在编码期填写 RED/GREEN 结果、每个关键断言的位置和真实组件证据；全部状态 verified 后任务才可 done。
+> `cf-task-start` 在编码期填写 functional/manual 的 RED/GREEN 结果、每个关键断言的位置和真实组件证据；E2E 仅登记测试与命令，执行统一留给 verify-e2e。全部 functional 状态 verified 后任务才可 done。
 
 ### Log
 - [<当前日期>] created (draft)

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

@@ -5,7 +5,8 @@
 ## 输入
 
 - `/cf-task:start <file> TASK-001` — 激活指定文件中的单个子任务
-- `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务
+- `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务；批次内独立任务默认并行派发子 agent
+- `/cf-task:start <file> --serial` — 整文件模式强制串行执行，不建 worktree
 
 其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略日期目录前缀和 `.md` 后缀。
 
@@ -22,8 +23,8 @@
 用 Read 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
-- `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
+- `in-progress` → 校验现有 marker 的需求目录、TASK-ID 与 Context；匹配且为 active 才继续步骤 2，跳过重复 Start。paused/blocked 先解除原因并调用 resume；marker 缺失或不匹配先 doctor，不能仅改 Markdown。
+- `done` / `verified` → 实现已完成；done 的 E2E 可为 e2e_deferred，转 verify-e2e 终验。发现缺口时报告并显式重新规划修复任务，不直接把终态改成 in-progress。
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -32,7 +33,7 @@
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
-- 所有依赖必须为 `done`
+- 所有依赖必须为 `done` 或 `verified`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
 **验收契约检查**：
@@ -60,12 +61,12 @@
 
 在改状态或生产代码前，顺序固定且不得跳步：
 
-1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/pending/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
-3. 只有前两步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+3. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令（E2E 只登记，不在本阶段执行）
+5. 先编写验收测试（E2E 只编写并登记）。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败。E2E 场景不执行 RED，登记为 e2e_deferred 留给 verify-e2e
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -83,11 +84,10 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
-2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
-3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
-4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
-5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
+1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
+2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
+3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
+4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
 
 ### 3.5 TASK-bound Spec Session
 
@@ -105,16 +105,18 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
 - `manual` 场景已有用户确认和可复核记录
 
-满足后：
-1. 用 Edit 更新 Status 为 `done`
-2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
-3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成`
+满足后，执行唯一收尾入口：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate（acceptance 场景 + spec verifiers + 全量 validation.yml，含 heavy）；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 
@@ -180,14 +182,81 @@ Spec 同步提示:
   - TASK-004: #NOTES 未解决
   - TASK-005: 依赖 TASK-004 (blocked)
 
-开始执行...
+开始执行（批次内默认并行派发子 agent，预检失败自动回退串行）...
 ```
 
-### 4. 按序执行
+### 4. 执行批次
+
+对每个批次执行；批次内仅 1 个 TASK、传入 `--serial`、或并行预检失败时，走 4.6 串行回退。
+
+#### 4.1 并行预检与 worktree 准备
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
+  --task-file "<任务文件相对路径>" --tasks TASK-001,TASK-003 --json
+```
+
+- 返回 `{"ok": true, "run_id": ..., "worktrees": [...]}` 才可并行；`ok: false` 时打印 `code`/`message` 并回退串行，禁止手工建 worktree/分支。
+- 预检内容：git 仓库、`.code-flow/.gitignore` 含 `worktrees/`、主 worktree 无 active marker、tracked 工作区干净。命令会自动提交仅位于当前需求目录内的流程产物（任务文件等）；需求目录以外存在未提交改动时拒绝并行，提示用户先提交或收起。
+
+#### 4.2 派发子 agent（平台自适应）
+
+若当前平台提供子 agent/Task 派发能力，为本批次每个 TASK 各派发一个子 agent（同一批并发不超过 3，超出时按 TASK 顺序拆成多轮）。子 agent prompt 必须包含 worktree 绝对路径、TASK-ID、任务文件相对路径，并声明以下硬性要求：
+
+1. 进入 worktree：所有命令 `cd <worktree>` 执行，文件读写使用该 worktree 内路径。
+2. 按本命令"单任务模式"步骤 1-4 完成该 TASK：`cf_spec_context.py start` → functional RED → 实现 → functional GREEN（E2E 只登记）→ `cf_task_workflow.py finish --root "<worktree>"`。
+3. 平台 hook 注入绑定主工作区；子 agent 必须显式读取 Spec Session（`.code-flow/specs/_session/task-*.md`）与详设章节，不得依赖自动注入。
+4. 完成时在 worktree 内提交全部改动（含任务文件 Checklist/Evidence/Status 更新），提交信息 `cf-task(<TASK-ID>): <标题>`。
+5. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+
+平台不支持子 agent 时，不建 worktree，直接走 4.6 串行回退。
+
+#### 4.3 收集与校验
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py collect --root "$PWD" --run-id <run_id> --json
+```
+
+- 每个任务必须 `ok: true`（改动已提交、Status 为 done/verified、marker 已清理、有提交）。
+- 任一任务失败：停止本批次，不合并；保留 worktree 并列出失败原因。修复后重跑 collect；确认放弃时执行 4.5 cleanup。
+
+#### 4.4 回并主分支
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
+按 TASK-ID 先后顺序逐个回并；先 rebase 再合并，让冲突只在任务自己的 worktree 内解决。
 
-完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
+1. 取主工作区当前分支名（主工作区执行 `git rev-parse --abbrev-ref HEAD`，记为 <主分支>），在任务 worktree 内对齐：
+
+```bash
+cd <worktree> && git rebase <主分支>
+```
+
+- rebase 冲突：读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ `git rebase --abort`，保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。
+- rebase 成功后重跑该任务的 functional 验收命令（E2E 留给 verify-e2e）；失败则在 worktree 内修复并提交，再执行 4.3 collect 复核。
+
+2. 回到主工作区合并（此时应无冲突）：
+
+```bash
+git merge --no-ff -m "merge cf-task <TASK-ID>" <branch>
+```
+
+- 仍出现冲突（主区期间有新合并）：按双方意图解决并重跑双方 functional 验收；通过后提交 merge。
+- 合并后验收失败：记录合并前 HEAD 并 `git reset --hard <合并前HEAD>`（分支与 worktree 原样保留），回到 4.2 让对应子 agent 修复后重新 collect / rebase / 合并。
+
+3. 全部任务合并完成后进入 4.5 清理。
+
+- E2E 验收留给 verify-e2e，不在本步骤执行。
+
+#### 4.5 清理
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py cleanup --root "$PWD" --run-id <run_id> --json
+```
+
+清理 worktree；已合入的分支自动删除，未合入的保留供排查。worktree 存在未提交改动时 cleanup 会拒绝，先人工确认再决定处理方式。全部批次完成后进入步骤 5。
+
+#### 4.6 串行回退
+
+未启用并行、批次仅 1 个任务或预检失败时，对批次内可激活子任务执行单任务模式步骤 3-4（详设已在步骤 2 加载，无需重复读取），完成一个后再解锁下一个。
 
 ### 5. 输出摘要与文档同步检查
 
@@ -212,3 +281,5 @@ Spec 同步提示:
 
   运行 /cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。

package/src/adapters/claude/commands/cf-task/verify-e2e.md

@@ -21,10 +21,10 @@ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶
 
 ### 1. 检查前置条件
 
-确认需求目录下所有子任务状态为 `done` 或 `verified`：
+确认需求目录下所有子任务状态为 `done`（实现完成）或 `verified`（终验已闭环）：
 
 ```bash
-rg "^Status:" <需求目录>/*.md
+rg "^- \*\*Status\*\*:" <需求目录>/*.md
 ```
 
 如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
@@ -53,20 +53,19 @@ E2E 场景需要以下环境：
 用户确认后，执行：
 
 ```bash
-python3 .code-flow/scripts/cf_acceptance_runner.py \
-  --manifest <需求目录>/.acceptance-manifest.json \
-  --root . \
-  --include-e2e \
-  --write-evidence
+python3 .code-flow/scripts/cf_task_workflow.py verify-e2e \
+  --task-dir "<需求目录>" --root "$PWD" --json
 ```
 
+该入口重新检查所有 TASK、锁定 manifest 和 functional/manual 最新证据，内部以 `--only-e2e` 调用 runner；只有全通过才把任务提升为 verified。不得手动改状态。
+
 ### 4. 报告结果
 
 解析执行结果：
 
 ```json
 {
-  "decision": "pass",
+  "decision": "block",
   "results": [
     {"id": "E-01", "kind": "e2e", "status": "passed"},
     {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
@@ -79,7 +78,7 @@ python3 .code-flow/scripts/cf_acceptance_runner.py \
 
 ### 5. 更新任务状态
 
-所有 E2E 通过后，将需求目录下的任务状态更新为 `verified`（如果当前是 `done`）。
+确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
 
 ## 失败处理
 

package/src/adapters/claude/commands/cf-validate.md

@@ -4,7 +4,7 @@
 
 ## 输入
 
-- `/project:cf-validate` — 基于 git diff 自动获取变更文件
+- `/project:cf-validate` — 自动获取任务基线或 Git 全部变更文件
 - `/project:cf-validate src/Foo.tsx` — 验证指定文件
 - `/project:cf-validate --files=src/a.ts,src/b.ts` — 验证多个文件
 
@@ -15,10 +15,10 @@
 用 Bash 执行：
 
 ```bash
-git diff --name-only HEAD
+python3 .code-flow/scripts/cf_validation.py --root "$PWD" --scope-only --json
 ```
 
-如果用户指定了文件路径，使用用户指定的文件。如果无变更文件，输出"无变更需要验证"。
+有 active TASK 时使用冻结基线以来的全部任务变更（含已提交文件）；无 active TASK 时包含暂存、未暂存和未跟踪文件。用户指定路径时用 `--files "src/a.py" "src/b.py"` 原样传递；若结果确实为空才输出“无变更需要验证”。
 
 ### 2. 读取验证规则
 
@@ -32,19 +32,21 @@ validators:
     trigger: "**/*.{ts,tsx}"
     command: "npx tsc --noEmit"
     timeout: 30000
+    heavy: false          # true = Stop 每轮跳过，finish 与 /cf-validate 执行
     on_fail: "修复建议"
 ```
 
+全量测试 / e2e 等慢命令标 `heavy: true`：Stop 每轮跳过，**任务 finish 自动执行一次**，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
+
 ### 3. 匹配并执行验证
 
-对每条验证规则：
-- 将 `trigger` glob 与变更文件列表做匹配
-- 匹配到 → 用 Bash 执行 `command`
-  - 如果 command 包含 `{files}` → 替换为匹配到的文件路径列表，**每个路径用单引号包裹**（如 `'src/foo.ts' 'src/bar.ts'`）
-  - 如果 command 不含 `{files}` → 直接执行原命令（如 `npx tsc --noEmit` 本身就检查全局）
-- 未匹配 → 跳过该规则
+执行统一验证入口：
+
+```bash
+python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
+```
 
-每条命令使用对应的 `timeout` 值（毫秒）。
+显式范围追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；同一运行内相同 argv/cwd/timeout 去重，跨运行不复用。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
 
 ### 4. 汇总结果
 
@@ -61,13 +63,13 @@ validators:
 
 ## 安全设计
 
-- 对 `{files}` 中的每个文件路径用单引号包裹，防止 shell 注入
-- 仅接受 `git diff` 输出的文件路径或用户显式指定的路径
+- `{files}` 直接展开为 argv 参数；带空格、引号的路径仍是一个参数，不手工拼接引号或执行 shell
+- 范围来自任务基线、Git 状态（包括 untracked）或用户显式指定的路径
 - 用户指定的路径必须位于项目根目录内
 
 ## 异常处理
 
 - validation.yml 不存在 → 尝试检测 package.json scripts 中的 test/lint 命令
 - 命令执行超时 → 输出超时提示，建议增大 timeout 或缩小验证范围
-- 命令不存在 → 提示安装依赖（如 `pip install mypy`）
+- 命令不存在或配置无效 → 返回 block 并提示所缺依赖，不当作验证通过
 - 无变更文件 → 输出"无变更需要验证"

package/src/adapters/codex/skills/cf-init/SKILL.md

@@ -69,6 +69,7 @@ description: Initialize the code-flow spec system in a project. Use when setting
 - Python 后端项目：删除 `TypeScript 类型检查`、`Vue 类型检查`、`ESLint`、`Stylelint`、`前端单元测试`
 - Go/Rust/Java 后端：删除前端 validator；如果没有对应语言 validator，保留文件并在摘要中提示用户补充
 - fullstack / generic：全部保留，除非项目明确没有对应语言文件
+- 全量测试 / e2e 等慢命令（`pytest`、`vitest run`、Playwright 等）标 `heavy: true`：Stop 每轮跳过，任务 finish 自动执行一次，也可 `cf-validate` 手动执行
 
 若 `.code-flow/validation.yml` 缺失，提示用户重跑 `code-flow init`，不要手工拼装 YAML。
 

package/src/adapters/codex/skills/cf-spec/SKILL.md

@@ -52,5 +52,9 @@ description: Manage schema-v1 Spec Context, drift recovery, and prepared one-sho
 ## doctor
 
 1. 校验 config schema、active marker、lock、Context hash、task/status、migration journal 和 legacy residue。
-2. active marker 存在时执行 `cf_spec_context.py active doctor`，传入可证明的 Context hash；无法证明时保持 `recovery_required`。
-3. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。
+2. 按场景恢复，禁止删除 marker、手改状态或越过 required Gate：
+   - **Context hash drift**（`status` 显示 marker hash 漂移）：先执行 refresh，它会自动重同步 marker hash；成功后继续原流程，不要用 doctor。
+   - **marker 停在 `activating`（start 事务中断）**：取 `status --json` 的 `context_sha256` 执行 `active doctor`；hash/head 可证明时自动恢复 active，无法证明时加 `--resync` 重新绑定。
+   - **marker 损坏或归属无法证明**：向用户说明影响，仅在用户明确确认放弃该 TASK 后执行 `active doctor --abandon`，随后重新规划该任务。
+3. `active doctor` 返回 `recovery_required`（退出码 3）是诊断结果而非崩溃：按第 2 步选择 refresh / `--resync` / `--abandon`，不要用 `--help` 探测或反复重试。
+4. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。

package/src/adapters/codex/skills/cf-task-archive/SKILL.md

@@ -17,7 +17,7 @@ description: Archive a completed task file after completeness, correctness, trac
 
 1. 读取匹配到的 task 文件
 2. 提取所有 `## TASK-xxx` 段落的 Status
-3. 检查是否所有子任务均为 `done`
+3. 检查是否所有子任务均为 `verified`（E2E 终验后的终态；仍为 `done` 说明 verify-e2e 尚未执行，先跑它）
 
 若有未完成子任务，拒绝归档并输出：
 
@@ -37,24 +37,24 @@ description: Archive a completed task file after completeness, correctness, trac
 
 - 需求目录必须存在 `spec-context.yml`；执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`
 - 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage code --json`；required Rule 的 stale/pending/conflict/unverified 任一存在即 FAIL
-- 若 `.code-flow/.active-task.json` 仍指向本需求，必须先完成对应 TASK 的 Done Gate，并以 `{"gate_passed": true}` 调用 `active complete`；不得通过归档绕过 active 状态
+- 若 `.code-flow/.active-task.json` 仍指向本需求，先执行 `python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`，通过后再 verify-e2e；不得自报 gate_passed 或通过归档绕过 active 状态
 - Context 与 Evidence 随需求目录一并归档，`_session` 仅是可重建投影，不是事实源
 
-所有子任务 done 后，执行四维校验：
+所有子任务 verified 后，执行四维校验：
 
 **完整性**：
 - 所有 Checklist 项已勾选
 - 全文无残留的 `#NOTES` 标记
 
 **正确性**：
-- 如果 `.code-flow/validation.yml` 存在，读取验证规则，用 shell 命令执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
+- 执行 `python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json`；归档时任务已无 marker，须补充本需求基线至当前的变更路径作为 `--files` 参数，不能把工作区干净误认为本需求无需验证
 - 检查本次变更涉及的文件是否通过 lint/type check
 
 **验收追溯**：
 - 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
 - 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
 - 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
-- 汇总并重新执行契约中所有唯一验收命令；测试未收集、未执行或失败均为 FAIL
+- 先用 `cf_acceptance_manifest.py --task-file "<任务文件>" --output "<需求目录>/.acceptance-manifest.json" --verify-plan` 校验基线，再用 `cf_acceptance_runner.py --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --include-e2e --write-evidence` 统一复验。相同 argv、cwd、timeout 的命令在单次运行内复用结果；跨运行不复用，依赖步骤不跨状态屏障复用。测试未收集、未执行或失败均为 FAIL
 - `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
 
 **一致性**：

package/src/adapters/codex/skills/cf-task-block/SKILL.md

@@ -15,17 +15,23 @@ description: Mark a subtask as blocked with a reason. Use when a task cannot pro
 
 1. 用 `rg --files` 或 `find` 定位任务文件，读取
 2. 定位 `## TASK-001` 段落，检查当前 Status：
-   - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
+   - `done` / `verified` → 拒绝：`TASK-001 已完成，无法标记阻塞`
    - `blocked` → 提示：`TASK-001 已处于 blocked 状态`，仍追加新的阻塞原因
    - `draft` / `in-progress` → 继续
-3. 用 apply_patch 更新 Status 为 `blocked`
-4. 在 `### Log` 前追加：`> BLOCKED: <阻塞原因>`
-5. 在 `### Log` 追加：`- [<当前日期>] blocked (<阻塞原因>, was <原状态>)`
-6. 更新文件头 `Updated` 日期
-7. 输出确认：`TASK-001 已标记为 blocked: <原因>`
+3. 调用统一 workflow service 入口（与 active block 同一状态机），不要先编辑状态或 marker：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py block --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --reason "<阻塞原因>" --json
+```
+
+命令同时更新 Status、阻塞原因、Log、Updated 和匹配的 marker；无 marker 的 draft 任务只改变任务文档。仅在返回成功后确认阻塞；其他需求的 marker 不得改动。
 
 ## 解除阻塞
 
-阻塞的解除不通过本命令操作，而是：
-- 如果是 Notes 导致的阻塞 → 用 `cf-task-note` 与 AI 讨论解决后自动解除
-- 如果是 `[BLOCKED]` 标记 → 用户手动编辑文件移除 `[BLOCKED]` 条目，或用 `cf-task-start` 重新启动（需所有阻塞条件清除）
+先解决 Notes 或外部依赖，再执行：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+resume 会检查未解决的 #NOTES 和依赖，原子同步任务与 marker。未激活的 blocked 任务恢复 draft；已有匹配 marker 的任务恢复 in-progress。失败时保留阻塞状态，不通过手动改 Status 绕过。

package/src/adapters/codex/skills/cf-task-graph/SKILL.md

@@ -14,6 +14,12 @@ description: Visualize task dependency DAG, identify parallelizable task groups
 
 ## 执行步骤
 
+### 0. 程序计算（推荐）
+
+用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK；批次内的独立任务由 cf-task-start 在各自 worktree 中并行派发子 agent（预检失败自动回退串行），详见 cf-task-start 步骤 4。
+
+`batches` 是组内可独立开发的拓扑批次；`dependency_components` 是依赖连通分组，只保证组与组之间独立，组内仍有先后依赖。`independent_groups` 仅为后者的兼容别名，不要把它显示成组内并行。
+
 ### 1. 读取任务数据
 
 - 指定文件：用 `rg --files` 或 `find` 定位后读取
@@ -66,7 +72,8 @@ Layer 2:
 按子任务状态标注：
 - `[draft]` — 待启动
 - `[in-progress]` — 进行中
-- `[done]` — 已完成
+- `[done]` — 实现完成，E2E 可能仍待终验
+- `[verified]` — 终验完成
 - `[blocked]` — 被阻塞（附原因）
 
 ### 5. 多文件模式

package/src/adapters/codex/skills/cf-task-note/SKILL.md

@@ -131,10 +131,7 @@ TASK-002:
 所有 `#NOTES` 讨论完毕后：
 
 1. 再次扫描文件，确认无残留 `#NOTES` 标记
-2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`：
-   - 扫描 `### Log`，查找 `blocked` 记录中的原状态
-   - 用 apply_patch 恢复原状态
-   - 在 `### Log` 追加：`- [<当前日期>] unblocked (all #NOTES resolved, restored to <原状态>)`
+2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`，清除当前阻塞条目后调用 `python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`。命令检查依赖和残留 Notes，同步 marker 与任务状态；不得从历史 Log 猜测状态后只改 Markdown。失败保留 blocked 并报告原因。
 3. 更新文件头 `Updated` 日期
 
 ### 6. 输出摘要