@michaelxwb/code-flow 0.6.3 → 0.6.5

package/src/adapters/costrict/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,100 @@ 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、遗留问题。
+
+标准 worker prompt 模板（替换占位符后派发）：
+
+```
+你在隔离 worktree 中执行 <TASK-ID>：<worktree 绝对路径>。
+1) cd 到 worktree；先读 Spec Session（.code-flow/specs/_session/task-<name>.md）、任务文件的当前 TASK 段落与 design 来源章节；
+2) cf_spec_context.py start → 写验收测试记录 RED → 实现 → GREEN；
+3) 运行 cf_task_workflow.py finish --root "$PWD" --task <TASK-ID> --json；decision=pass 后【再】提交全部改动（含 finish 回写的 Evidence/状态）：git add -A && git commit -m "cf-task(<TASK-ID>): <标题>"；
+4) 返回摘要：TASK-ID、Status、验收命令与结果、commit SHA、遗留问题。
+```
+
+> 提交必须在 finish 之后：finish 通过后会回写 Evidence/状态；collect 默认会自动提交这些回写，但显式提交更清晰。
+
+子 agent 中断（取消/超时）时不要重新 prepare：检查该 worktree 的 `git status`、`git log <base>..HEAD` 与 marker——
+- 无改动且无 marker：直接接管，按单任务模式继续；
+- 有未提交改动或已有提交但未 done：在 worktree 内接管收尾（补实现/测试并 finish），再走 4.3 collect；
+- 已 done 且 marker 已清理：直接进入 4.3。
+
+平台不支持子 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 已清理、有提交）。
+- `collect` 在任务 done/verified 且 marker 已清理后，会自动提交 finish 回写的 Evidence/状态（`--no-commit` 关闭并回到严格模式）；finish 之外的未提交改动仍应人工确认。
+- 任一任务失败：停止本批次，不合并；保留 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。
+- 状态文件冲突（`spec-context.yml` / 任务 md 的覆盖状态列 / `.acceptance-manifest.json`）按确定性优先级解决：覆盖状态列取并集（两边各自 verified 的行保留 verified）；`spec-context.yml` 取已包含全量规则证据的一侧；manifest 多数情况按行自动合并，冲突时以任务文件为准重建后重跑 functional 场景。解决后必须 `cf_spec_context.py refresh` 收敛 hash，并重跑合并双方的 functional 验收与 `cf_spec_gate --stage code --json`，通过后提交 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 +300,5 @@ Spec 同步提示:
 
   运行 /cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。

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

@@ -9,7 +9,12 @@ globs: []
 
 ## 使用场景
 
-E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+本命令是**需求级终验**入口，在所有子任务的 functional 测试通过后统一执行：
+
+1. **review 层 verifier**：绑定规范中 `stage: review` 的 required verifier（e2e/acceptance/构建等重型验证）。遍历需求目录全部 task context，按 spec/rule 去重执行一次，证据写回全部相关 context；输出 `executed` / `reused` / `failed` 计数。
+2. **E2E 验收场景**：依赖外部环境（数据库、API、浏览器等）、编码阶段标记 `e2e_deferred` 的场景。
+
+失败不写 verified、不反转已 done 的任务状态；归档前必须 `decision=pass`。未声明 review verifier 且无 E2E 场景时为空操作（`reason=nothing_to_verify`）。
 
 ## 调用方式
 

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

@@ -68,6 +68,7 @@ description: 一键初始化项目规范体系，检测技术栈，生成 spec
 - 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。
 
@@ -156,18 +157,22 @@ AGENTS.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 OpenCode 插件配置
 
+OpenCode v2 会自动加载 `.opencode/plugins/` 下的插件目录，无需在 `opencode.json` 中声明。
 检查 `opencode.json` 是否存在。如果不存在，创建：
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [".opencode/plugins/code-flow"]
+  "$schema": "https://opencode.ai/config.json"
 }
 ```
 
-如果 `opencode.json` 已存在，只合并缺失的 `plugin` 条目，保留用户已有配置。
+如果 `opencode.json` 已存在，只做 v1→v2 迁移，保留用户已有配置：
+- 删除遗留的顶层 `plugin` 键（v1 写法，如 `".opencode/plugins/code-flow"`）；其中非本地的用户条目搬入 `plugins`。
+- 不要向 `plugins` 写入 `.opencode/plugins/code-flow`（自动发现已覆盖，显式声明会导致重复加载或包解析告警）。
 
-确保 `.opencode/plugins/code-flow/` 已存在。OpenCode 通过插件转发 `chat.message` 并注入 specs，不需要生成 Claude/Costrict 风格的 settings 文件。
+确保 `.opencode/plugins/code-flow/` 已存在且为 v2 形态（默认导出 `{ id: "code-flow", setup }`，不依赖 `@opencode/plugin` 包），
+注册 `session.prompt` / `tool.execute.after` / `session.context` hooks + `event.subscribe` 订阅 `session.idle`）。
+OpenCode 通过插件转发用户 prompt 并经 context hook 注入 specs，不需要生成 Claude/Costrict 风格的 settings 文件。
 
 ### 7. 安装 pyyaml
 

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

@@ -51,5 +51,9 @@ description: 管理 Spec Context、漂移恢复与一次性迁移
 ## 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/opencode/commands/cf-task/archive.md

@@ -41,6 +41,8 @@ description: 归档已完成的 task 文件
 
 - 需求目录必须存在 `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
+- 执行 review 终验：`python3 .code-flow/scripts/cf_task_workflow.py verify-e2e --task-dir <需求目录> --root "$PWD" --json`（聚合需求目录全部 task context 的 `stage: review` verifier + acceptance E2E，按 spec/rule 去重执行一次并写回证据）；`decision=pass` 才继续，失败保持阻断
+- 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage review --json`；required Rule 存在 unverified review 证据即 FAIL（先完成 review 终验）
 - 若 `.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` 仅是可重建投影，不是事实源
 

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

@@ -19,7 +19,7 @@ description: 可视化子任务依赖关系 DAG
 
 ### 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/opencode/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/opencode/commands/cf-task/start.md

@@ -10,7 +10,8 @@ description: 激活子任务并开始编码
 ## 输入
 
 - `/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` 后缀。
 
@@ -68,9 +69,9 @@ description: 激活子任务并开始编码
 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`：
 
@@ -88,7 +89,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 失效。
@@ -120,7 +121,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`。
 
@@ -186,14 +187,100 @@ 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、遗留问题。
+
+标准 worker prompt 模板（替换占位符后派发）：
+
+```
+你在隔离 worktree 中执行 <TASK-ID>：<worktree 绝对路径>。
+1) cd 到 worktree；先读 Spec Session（.code-flow/specs/_session/task-<name>.md）、任务文件的当前 TASK 段落与 design 来源章节；
+2) cf_spec_context.py start → 写验收测试记录 RED → 实现 → GREEN；
+3) 运行 cf_task_workflow.py finish --root "$PWD" --task <TASK-ID> --json；decision=pass 后【再】提交全部改动（含 finish 回写的 Evidence/状态）：git add -A && git commit -m "cf-task(<TASK-ID>): <标题>"；
+4) 返回摘要：TASK-ID、Status、验收命令与结果、commit SHA、遗留问题。
+```
+
+> 提交必须在 finish 之后：finish 通过后会回写 Evidence/状态；collect 默认会自动提交这些回写，但显式提交更清晰。
+
+子 agent 中断（取消/超时）时不要重新 prepare：检查该 worktree 的 `git status`、`git log <base>..HEAD` 与 marker——
+- 无改动且无 marker：直接接管，按单任务模式继续；
+- 有未提交改动或已有提交但未 done：在 worktree 内接管收尾（补实现/测试并 finish），再走 4.3 collect；
+- 已 done 且 marker 已清理：直接进入 4.3。
+
+平台不支持子 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 已清理、有提交）。
+- `collect` 在任务 done/verified 且 marker 已清理后，会自动提交 finish 回写的 Evidence/状态（`--no-commit` 关闭并回到严格模式）；finish 之外的未提交改动仍应人工确认。
+- 任一任务失败：停止本批次，不合并；保留 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。
+- 状态文件冲突（`spec-context.yml` / 任务 md 的覆盖状态列 / `.acceptance-manifest.json`）按确定性优先级解决：覆盖状态列取并集（两边各自 verified 的行保留 verified）；`spec-context.yml` 取已包含全量规则证据的一侧；manifest 多数情况按行自动合并，冲突时以任务文件为准重建后重跑 functional 场景。解决后必须 `cf_spec_context.py refresh` 收敛 hash，并重跑合并双方的 functional 验收与 `cf_spec_gate --stage code --json`，通过后提交 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. 输出摘要与文档同步检查
 
@@ -218,3 +305,5 @@ Spec 同步提示:
 
   运行 /cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。

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

@@ -9,7 +9,12 @@ globs: []
 
 ## 使用场景
 
-E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+本命令是**需求级终验**入口，在所有子任务的 functional 测试通过后统一执行：
+
+1. **review 层 verifier**：绑定规范中 `stage: review` 的 required verifier（e2e/acceptance/构建等重型验证）。遍历需求目录全部 task context，按 spec/rule 去重执行一次，证据写回全部相关 context；输出 `executed` / `reused` / `failed` 计数。
+2. **E2E 验收场景**：依赖外部环境（数据库、API、浏览器等）、编码阶段标记 `e2e_deferred` 的场景。
+
+失败不写 verified、不反转已 done 的任务状态；归档前必须 `decision=pass`。未声明 review verifier 且无 E2E 场景时为空操作（`reason=nothing_to_verify`）。
 
 ## 调用方式
 

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

@@ -36,9 +36,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/opencode/opencode.json

@@ -1,4 +1,3 @@
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [".opencode/plugins/code-flow"]
+  "$schema": "https://opencode.ai/config.json"
 }