@michaelxwb/code-flow 0.6.3 → 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.3",
+  "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/graph.md

@@ -15,7 +15,7 @@
 
 ### 0. 程序计算（推荐）
 
-用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK：批次内“可并行”指可独立开发，而非可同时激活。
+用 `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` 仅为后者的兼容别名，不要把它显示成组内并行。
 

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` 后缀。
 
@@ -63,9 +64,9 @@
 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. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+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,7 +84,7 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行 functional 验收和受影响范围的回归测试；E2E 已在编码前锁定场景、断言、真实边界和命令，完整 GREEN 留给 verify-e2e。
+1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
 2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
 3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
 4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
@@ -115,7 +116,7 @@ RED 证据写入 `Acceptance Evidence`：
 python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
 ```
 
-该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate（acceptance 场景 + spec verifiers + 全量 validation.yml，含 heavy）；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 
@@ -181,14 +182,81 @@ Spec 同步提示:
   - TASK-004: #NOTES 未解决
   - TASK-005: 依赖 TASK-004 (blocked)
 
-开始执行...
+开始执行（批次内默认并行派发子 agent，预检失败自动回退串行）...
 ```
 
-### 4. 按序执行
+### 4. 执行批次
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
+对每个批次执行；批次内仅 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 回并主分支
+
+按 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. 输出摘要与文档同步检查
 
@@ -213,3 +281,5 @@ Spec 同步提示:
 
   运行 /cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。

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

@@ -32,9 +32,12 @@ 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. 匹配并执行验证
 
 执行统一验证入口：

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-graph/SKILL.md

@@ -16,7 +16,7 @@ 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：批次内“可并行”指可独立开发，而非可同时激活。
+用 `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` 仅为后者的兼容别名，不要把它显示成组内并行。
 

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

@@ -226,7 +226,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
@@ -240,7 +240,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/codex/skills/cf-task-start/SKILL.md

@@ -6,7 +6,8 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 ## 输入
 
 - `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` 后缀。
 
@@ -64,9 +65,9 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 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. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+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`：
 
@@ -84,7 +85,7 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行 functional 验收和受影响范围的回归测试；E2E 已在编码前锁定场景、断言、真实边界和命令，完整 GREEN 留给 verify-e2e。
+1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
 2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
 3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
 4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
@@ -116,7 +117,7 @@ RED 证据写入 `Acceptance Evidence`：
 python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
 ```
 
-该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate（acceptance 场景 + spec verifiers + 全量 validation.yml，含 heavy）；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 
@@ -182,14 +183,81 @@ Spec 同步提示:
   - TASK-004: #NOTES 未解决
   - TASK-005: 依赖 TASK-004 (blocked)
 
-开始执行...
+开始执行（批次内默认并行派发子 agent，预检失败自动回退串行）...
 ```
 
-### 4. 按序执行
+### 4. 执行批次
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
+对每个批次执行；批次内仅 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 回并主分支
+
+按 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. 输出摘要与文档同步检查
 
@@ -214,3 +282,5 @@ Spec 同步提示:
 
   运行 cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `cf-task-verify-e2e <需求目录>` 执行延迟的 E2E 终验。

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

@@ -33,9 +33,12 @@ 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. 匹配并执行验证
 
 执行统一验证入口：

package/src/adapters/costrict/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/costrict/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/costrict/commands/cf-task/graph.md

@@ -15,7 +15,7 @@
 
 ### 0. 程序计算（推荐）
 
-用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK：批次内“可并行”指可独立开发，而非可同时激活。
+用 `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` 仅为后者的兼容别名，不要把它显示成组内并行。
 

package/src/adapters/costrict/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)