@michaelxwb/code-flow 0.6.4 → 0.8.1

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

@@ -1,8 +1,3 @@
----
-description: 激活子任务并开始编码
----
-
-
 # cf-task:start
 
 激活子任务并开始编码。支持单任务模式和整文件模式。
@@ -34,7 +29,7 @@ description: 激活子任务并开始编码
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
 - 如果存在 `#NOTES` 标记，说明用户 review 时留下了未讨论的问题，拒绝启动
-- 输出：`前置检查失败：以下 #NOTES 未解决\n- 密码加密存储  #NOTES 用 bcrypt 还是 argon2？\n- ...\n请先运行 /project:cf-task:note <file> TASK-xxx 讨论并解决`
+- 输出：`前置检查失败：以下 #NOTES 未解决\n- 密码加密存储  #NOTES 用 bcrypt 还是 argon2？\n- ...\n请先运行 /cf-task:note <file> TASK-xxx 讨论并解决`
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
@@ -46,6 +41,9 @@ description: 激活子任务并开始编码
 - `Acceptance-Refs` 中每个 S-/E-/B- 都必须出现在全局覆盖表和当前契约中，测试层级与关键真实边界必须和 design 一致
 - 旧 task 没有覆盖表但来源 design 含结构化验收场景时，先从 design 回填覆盖表与契约；回填完成前不得修改生产代码
 - 非行为类任务可显式写 `Acceptance-Refs: N/A`；不得用 N/A 跳过已有设计场景
+- E2E 必须已通过 plan 精度门禁：P0/P1、`why_e2e`、`boundary`、非 smoke 的 `trigger_paths` 缺一不可；`start` 会在 `e2e_plan.quality.ok=false` 时阻断，不要手工改 manifest 绕过
+- 有 canonical 场景源时，start 同时复核浏览器边界、expected_refs 和延后责任信息。沿用 plan 已登记的可收集测试骨架；按当前 TASK 补齐断言并执行 functional RED/GREEN；关键 E2E 可在相关批次完成后验证，剩余缺口由需求终验核对。
+- 显式 `exec: deferred` 保留在 owned/smoke 提示中，但不进入 scheduled，也不在 Start 收集。旧锁文件缺少 `quality_schema: 2` 时保留原门禁并提示 `legacy_quality_schema`；按提示补字段、重锁和验证计划，不宣称新质量检查已通过。Done 阶段的显式延期场景允许 e2e_deferred，verified 仍须完整验收。
 
 ### 2. 加载详设上下文
 
@@ -66,12 +64,12 @@ 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 不单独阻止激活；不新增阶段状态门禁。
+1. 调用 `code-flow task 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 的测试用例名和可单独执行的命令（E2E 只登记，不在本阶段执行）
-5. 先编写验收测试（E2E 只编写并登记）。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败。E2E 场景不执行 RED，登记为 e2e_deferred 留给 verify-e2e
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令（E2E 先登记真实边界与执行方式）
+5. 先编写验收测试（E2E 编写并登记真实边界）。从 `start` 返回的 `e2e_plan` 读取范围：只编写 `owned` 中的 E2E；`smoke` 由相关批次或需求级 verify 运行，不在本 TASK 重写；`deferred` 中的 E2E 不得顺手补。E2E 必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. E2E 只断言用户可观察结果和真实链路；禁止断言源码字符串、CSS、组件宽度、字段顺序、文案顺序。UI 布局/交互细节应下沉到 component 测试。关键 E2E 可随相关批次运行；未运行者登记为 e2e_deferred，终验检查剩余证据。新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因；纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -89,7 +87,7 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
+1. 执行 functional 验收和受影响范围的回归测试；登记 E2E 场景、断言、真实边界和命令；按已就绪的相关批次运行关键 smoke，其余留作终验证据缺口；manual 场景只登记 `manual_pending`（原因、边界、验收方式），人工确认统一留给 verify-e2e。
 2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
 3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
 4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
@@ -110,20 +108,25 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
+- functional 在契约、证据和覆盖表中均为 `verified`；E2E 可为 `e2e_deferred`，`manual` 场景与 review 层 manual 规则延后到需求级终验由用户确认，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
-- `manual` 场景已有用户确认和可复核记录
+- E2E 按 `e2e_plan.owned` 登记，没有把 `deferred` 场景补成本任务测试；新增 E2E 必须回到 plan 重新过质量门禁
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；相关批次关键 E2E 可先验证，终验补足证据缺口
+- 显式 `stage: code` 的 manual 规则已有用户确认和可复核记录；默认 review 层的 manual 规则与 manual 场景在 verify-e2e 一次性确认
+
+普通 task 完成后，相关批次可执行 `code-flow task verify --task-dir "<需求目录>" --tasks TASK-001 --layers validators,e2e --profile smoke --root "$PWD" --json`。只选择依赖已就绪的关联 smoke；`not_ready` 或失败保留真实状态，不阻断无关任务。不要将全域浏览器或容量检查作为每个普通 task 的默认工作。
 
 满足后，执行唯一收尾入口：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+code-flow task 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 绕过验证。
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate：本任务范围（`Spec-Refs` ∪ 改动路径命中）的 code verifier + 本任务 acceptance 场景 + 轻量 validation.yml（不含 heavy）；范围外且明确归属需求级 review 的 verifier 标记 `deferred_to_review`，`heavy: true` validator 标记 `deferred_heavy`，统一在需求级 verify-e2e / 归档全量补跑；本任务 required code 检查因预算、环境或其他原因未执行时进入 `provisional`，保留 active marker，补齐检查后重新执行 finish，不能标记 done；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
-任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+Done Gate 只执行 code 层验证；review 层 manual 规则与 manual 场景不逐任务确认，延后到需求级 verify-e2e（返回 `manual_confirmation_required` 时按该命令的「人工验收确认」流程一次性确认）。
+
+验收断言失败时保持 `in-progress`；required code 检查未执行时由运行时转为 `provisional`。明确列出缺口，不能标记为 `done`。
 
 ### 5. 文档同步检查
 
@@ -197,7 +200,7 @@ Spec 同步提示:
 #### 4.1 并行预检与 worktree 准备
 
 ```bash
-python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
+code-flow task parallel prepare --root "$PWD" \
   --task-file "<任务文件相对路径>" --tasks TASK-001,TASK-003 --json
 ```
 
@@ -209,52 +212,61 @@ python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
 若当前平台提供子 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`）与详设章节，不得依赖自动注入。
+2. 按本命令"单任务模式"步骤 1-4 完成该 TASK：`code-flow task start` → functional RED → 实现 → functional GREEN（E2E 按计划登记并在相关批次验证）→ `code-flow task finish --root "<worktree>"`。
+3. 平台 hook 注入绑定主工作区；子 agent 必须显式读取 Spec Session（路径取 start 返回的 `session_output`，默认 `.code-flow/specs/_session/task-<任务文件stem>.md`）与详设章节，不得依赖自动注入。
 4. 完成时在 worktree 内提交全部改动（含任务文件 Checklist/Evidence/Status 更新），提交信息 `cf-task(<TASK-ID>): <标题>`。
-5. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+5. `finish` 返回 `decision: block` 时不得提交：保留现场，原样回报阻断原因（如 scope expansion 新增 required Spec、验收失败）与 `code-flow spec status --json` 输出，由主 agent 决定局部 Plan/Align、修复后重派或接管；不得自行 resume 绕过门禁。
+6. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+
+标准 worker prompt 模板（替换占位符后派发）：
+
+```
+你在隔离 worktree 中执行 <TASK-ID>：<worktree 绝对路径>。
+1) cd 到 worktree；先读 Spec Session（start 返回的 session_output，默认 .code-flow/specs/_session/task-<任务文件stem>.md）、任务文件的当前 TASK 段落与 design 来源章节；
+2) code-flow task start → 写验收测试记录 RED → 实现 → GREEN；
+3) 运行 code-flow task 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
+code-flow task parallel 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 内对齐：
+按 TASK-ID 先后顺序回并。统一入口自动完成：worktree 内 rebase → 状态文件冲突按确定性并集规则解决 → 主工作区 `--no-ff` 合并 → `code-flow spec refresh` 收敛 hash：
 
 ```bash
-cd <worktree> && git rebase <主分支>
+code-flow task parallel merge --root "$PWD" --run-id <run_id> --json
 ```
 
-- rebase 冲突：读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ `git rebase --abort`，保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。
-- rebase 成功后重跑该任务的 functional 验收命令（E2E 留给 verify-e2e）；失败则在 worktree 内修复并提交，再执行 4.3 collect 复核。
+- 返回 `ok: true` 才继续；`already_merged` 表示该任务已并入（幂等，可重跑）；任一任务失败即停止，修复后重跑 merge 续跑。
+- `code_conflict`：代码文件冲突无法程序化合并（返回冲突文件列表，rebase 已中止、主工作区未受影响）。人工读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ 保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。解决后重跑 merge。
+- 状态文件冲突（任务 md 覆盖状态列 / `spec-context.yml` / `.acceptance-manifest.json`）由 merge 自动按确定性并集规则处理，无需手工编辑：覆盖状态列两边各自 verified 的行均保留；`spec-context.yml` 取证据并集、verified 优先；manifest 按 verified/revision 合并。
+- merge 成功后自动执行 `refresh` 并在结果中返回 `pass` / `block: ...`；随后重跑合并双方的 functional 验收与 `cf_spec_gate --stage code --json`，失败则记录合并前 HEAD 并 `git reset --hard <合并前HEAD>`（分支与 worktree 原样保留），回到 4.2 让对应子 agent 修复后重新 collect / merge。
+- merge 运行关联批次 smoke；其他 E2E 由需求终验按证据缺口补验。
 
-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 清理。
 
 #### 4.5 清理
 
 ```bash
-python3 .code-flow/scripts/cf_task_parallel.py cleanup --root "$PWD" --run-id <run_id> --json
+code-flow task parallel cleanup --root "$PWD" --run-id <run_id> --json
 ```
 
 清理 worktree；已合入的分支自动删除，未合入的保留供排查。worktree 存在未提交改动时 cleanup 会拒绝，先人工确认再决定处理方式。全部批次完成后进入步骤 5。
@@ -288,3 +300,18 @@ Spec 同步提示:
 ```
 
 3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec status --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task start --task-dir "<需求目录>" --task-file "<任务文件>" --task TASK-001 --root "$PWD" --json
+code-flow task finish --task-dir "<需求目录>" --task TASK-001 --root "$PWD" --json
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow task parallel --help
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -4,6 +4,19 @@ description: 显示任务状态总览
 
 # cf-task:status
 
+
+## 命令面（0.8）
+
+`cf-task-status` 收敛了原先三个独立命令；旧命令保留一个 minor（0.9.0 移除）：
+
+| 子动作 | 等价旧命令 | 用途 |
+|--------|-----------|------|
+| `--notes` | `cf-task-note` | 讨论并收敛 `#NOTES` |
+| `--block` | `cf-task-block` | 标记阻塞并记录原因 |
+| `--graph` | `cf-task-graph` | 依赖 DAG 与并行批次 |
+
+带上述参数时，按对应旧命令章节的步骤执行；不带参数时行为不变。
+
 显示任务状态总览。
 
 ## 输入

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

@@ -1,15 +1,32 @@
 ---
-description: Execute deferred E2E scenarios after all functional tests pass
+description: Run layered verification or full requirement verification, including deferred E2E
 globs: []
 ---
 
 # cf-task:verify-e2e
 
+
+## 验证子动作（0.8）
+
+- `code-flow task verify --checks` — 等价于 `--layers validators`，是 `cf-validate` 的 0.8 入口。
+- `code-flow task verify-e2e --checks` 同样只跑 validators；需要包含 heavy validator 时显式指定 `--profile full`。仅 validators 可在任务进行中运行，使用 active TASK 基线以来的变更，不推进任务状态。
+- `cf-validate` 保留为兼容别名，0.9.0 移除。
+
 执行需求目录下被延迟的 E2E 验收场景。
 
 ## 使用场景
 
-E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+本命令是**需求级终验**入口，在所有子任务的 functional 测试通过后统一执行：
+
+1. **全量 verifier**：需求目录全部 task context 绑定的 required rules（code 层被任务延后的 `deferred_to_review` + `stage: review` 重型验证），按 spec/rule 去重全量执行一次，证据写回全部相关 context；输出 `executed` / `reused` / `failed` 计数。
+2. **E2E 验收场景**：依赖外部环境（数据库、API、浏览器等）、编码阶段标记 `e2e_deferred` 的场景；已通过且工作树内容指纹未变的场景跨运行复用（不重复执行 E2E），内容变化/失败自动重跑，`code-flow acceptance run --no-cache` 可强制全量。
+3. **全量 validation**：执行 `validation.yml` 全部 validator（含 `heavy: true` 全量套件/构建/E2E）；结果按工作树内容指纹缓存，归档复验命中即复用、不重复执行，`code-flow validate --no-cache` 强制重跑。
+
+失败不写 verified、不反转已 done 的任务状态；归档前必须 `decision=pass`。未声明 review verifier 且无 E2E 场景时为空操作（`reason=nothing_to_verify`）。
+
+> 0.8 分层入口：`code-flow task verify --layers validators,review,e2e --profile smoke|changed|full`。每层独立返回 `decision/executed/reused/failed/env_blocked/incomplete`，`profile` 默认 `changed`，`full` 必须显式；`task verify-e2e` 保留为兼容别名（全层 + full）。
+>
+> E2E 也按范围执行：`profile=changed` 只跑 `trigger_paths` 命中当前 diff 的 E2E，没有 `trigger_paths` 的 smoke E2E 不会在 changed 中顺跑；`profile=smoke` 只跑标记 `smoke` / `profile=smoke` 的 E2E（旧计划没有 smoke 标记时才回退全量 E2E）。不要把全量 E2E 当成每个小改动的默认门禁。
 
 ## 调用方式
 
@@ -27,58 +44,69 @@ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶
 rg "^- \*\*Status\*\*:" <需求目录>/*.md
 ```
 
-如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
+本步骤只适用于包含 review/e2e 的需求验证。如有 `in-progress` 或 `blocked` 任务，先完成任务；仅 `--checks` / `--layers validators` 不要求任务 done，但仍校验 active Context 与需求身份。
 
 ### 2. 检查环境依赖
 
-读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
+读取所选 checks 的 `env`、`env_scope`、`preflight` 声明。运行时在实际执行 check 前自动运行 preflight；已有有效证据时允许复用。不要从 `boundary` 猜测端口、数据库或驱动，也不要固定询问环境是否就绪。
 
-- `HTTP API` → 提示确认 API 服务运行中
-- `Browser` → 提示确认浏览器驱动已安装
-- `Database` → 提示确认测试数据库可访问
+收到 `env_blocked` 时，展示 `env_blocked_details` 中的 check ID、owner、失败的 preflight 命令、退出码和输出。根据真实失败修复可处理的本地问题；只有缺少外部配置、需要用户启动外部环境或涉及权限时请求用户输入。未声明 preflight 的检查仍按真实执行结果判断，不能自报环境已通过。
 
-显示清单并询问：
+### 3. 执行 E2E 场景
 
-```
-E2E 场景需要以下环境：
-  - 本地 API 服务 (http://localhost:3000)
-  - PostgreSQL 测试数据库
-  - Chrome WebDriver
+用户请求需求级终验时，执行：
 
-环境已就绪？(y/N)
+```bash
+code-flow task verify \
+  --task-dir "<需求目录>" --root "$PWD" \
+  --layers validators,review,e2e --profile full --json
 ```
 
-### 3. 执行 E2E 场景
+相关批次使用 `code-flow task verify --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke`；部分通过仅表示所选范围通过，不提升整个需求。日常增量验证使用 `--profile changed`，明确只跑 smoke 时使用 `--profile smoke`；不要把增量请求升级成全量。`code-flow task verify-e2e` 保留为默认全层 full 的兼容入口。仅检查代码时使用 `code-flow task verify --checks --task-dir "<需求目录>" --root "$PWD" --json`。
+
+全量终验重新检查所有 TASK、锁定 manifest 与 functional/manual 最新证据，执行全量 validation（含 heavy）和 code+review verifier（含 deferred 项）。runner 按范围执行 acceptance：仅 E2E 的路径使用 `--only-e2e`，full 或 functional 证据过期时同时复验所需 functional。只有全层 full 通过才将任务提升为 verified；单层、changed、smoke 通过均不推进状态。不得手动改状态。
 
-用户确认后，执行：
+### 4. 人工验收确认（manual_confirmation_required）
+
+需求中的 manual 验收默认落 review 层，编码阶段不逐任务打断，统一在这里确认。`verify-e2e` 返回 `reason=manual_confirmation_required` 时：
+
+1. 向用户完整展示 `manual_rules`（spec 规则、checklist、owner）与 `manual_scenarios`（场景 ID、真实边界），一次性请求确认；用户只确认部分时记录未确认的 ref/id。
+2. 用户明确回复后执行（`--confirmed-by` 必须是用户身份，Agent 不得代确认；`--source` 填写用户回复原文）：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py verify-e2e \
-  --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task confirm-manual \
+  --task-dir "<需求目录>" --root "$PWD" \
+  --confirmed-by "user:<用户>" --source "<用户回复原文>" --json
 ```
 
-该入口重新检查所有 TASK、锁定 manifest 和 functional/manual 最新证据，内部以 `--only-e2e` 调用 runner；只有全通过才把任务提升为 verified。不得手动改状态。
+部分确认时追加 `--refs <spec#RULE,...>` 与/或 `--scenarios <S-01,...>`。
+3. 重跑 `verify-e2e`；全部通过后任务才提升为 `verified`。
+
+> 显式声明 `stage: code` 的 manual 规则仍在任务 Done Gate 逐个确认，属于有意保留的强门禁。
 
-### 4. 报告结果
+### 5. 报告结果
 
 解析执行结果：
 
 ```json
 {
   "decision": "block",
-  "results": [
-    {"id": "E-01", "kind": "e2e", "status": "passed"},
-    {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
-  ]
+  "layers": {
+    "e2e": {
+      "decision": "block",
+      "checks": [{"id": "CHK-B", "status": "failed", "scenarios": ["E-02"]}]
+    }
+  }
 }
 ```
 
-- `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
-- `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
+- `decision=pass`：报告实际 `selected_layers`、`profile`、执行与复用计数，不将部分范围通过报告为全量终验完成
+- `decision=block`：列出失败层、场景 ID 与 check ID，从 `check_results` 或 `env_blocked_details` 展示对应命令、退出码和错误输出
+- `reason=manual_confirmation_required`：先按「人工验收确认」章节取得用户确认并执行 `confirm-manual`，再重跑本命令
 
-### 5. 更新任务状态
+### 6. 更新任务状态
 
-确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
+全层 full 通过后确认运行时已将任务 Status 更新为 `verified`，并保留原契约与运行历史。其他验证范围保留原状态。无需再次编辑状态。
 
 ## 失败处理
 
@@ -86,7 +114,7 @@ E2E 失败时：
 
 1. 显示失败场景的完整命令和退出码
 2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
-3. 不自动修改任务状态，等待用户修复后重新执行
+3. 修复可处理的问题后重跑所选范围；缺少用户输入时报告具体阻塞，不自动修改任务状态
 
 ## 示例
 
@@ -95,11 +123,7 @@ E2E 失败时：
 
 > 检查子任务状态... 所有任务已完成
 > 
-> E2E 场景需要以下环境：
->   - 本地 API 服务 (http://localhost:3000)
->   - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
-> 
-> 环境已就绪？(y/N) y
+> 按 checks 声明执行 preflight... 通过
 > 
 > 执行 E2E 场景...
 >   ✓ E-01: 用户登录流程 (1.2s)
@@ -108,3 +132,17 @@ E2E 失败时：
 > E2E 验收完成！2/2 场景通过
 > 已更新任务状态为 verified
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow task verify-e2e --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task confirm-manual --help
+code-flow acceptance run --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --write-evidence
+code-flow validate --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -2,15 +2,18 @@
 description: 根据变更文件自动匹配并执行验证规则
 ---
 
+
 # cf-validate
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-verify-e2e --checks`（运行时 `code-flow task verify --checks`）；保留一个 minor，0.9.0 移除。
+
 根据变更文件自动匹配并执行验证规则（测试、类型检查、lint），失败时自动尝试修复。
 
 ## 输入
 
-- `/project:cf-validate` — 自动获取任务基线或 Git 全部变更文件
-- `/project:cf-validate src/Foo.tsx` — 验证指定文件
-- `/project:cf-validate --files=src/a.ts,src/b.ts` — 验证多个文件
+- `/cf-validate` — 自动获取任务基线或 Git 全部变更文件
+- `/cf-validate src/Foo.tsx` — 验证指定文件
+- `/cf-validate --files=src/a.ts,src/b.ts` — 验证多个文件
 
 ## 执行步骤
 
@@ -19,7 +22,7 @@ description: 根据变更文件自动匹配并执行验证规则
 用 Bash 执行：
 
 ```bash
-python3 .code-flow/scripts/cf_validation.py --root "$PWD" --scope-only --json
+code-flow validate --root "$PWD" --scope-only --json
 ```
 
 有 active TASK 时使用冻结基线以来的全部任务变更（含已提交文件）；无 active TASK 时包含暂存、未暂存和未跟踪文件。用户指定路径时用 `--files "src/a.py" "src/b.py"` 原样传递；若结果确实为空才输出“无变更需要验证”。
@@ -36,21 +39,33 @@ validators:
     trigger: "**/*.{ts,tsx}"
     command: "npx tsc --noEmit"
     timeout: 30000
-    heavy: false          # true = Stop 每轮跳过，finish 与 /cf-validate 执行
+    heavy: false          # true = Stop 与 finish 跳过，需求终验与 /cf-validate 执行
     on_fail: "修复建议"
 ```
 
-全量测试 / e2e 等慢命令标 `heavy: true`：Stop 每轮跳过，**任务 finish 自动执行一次**，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
+全量测试 / e2e 等慢命令标 `heavy: true`：Stop 与任务 finish 跳过，由需求终验 / 归档执行，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
 
 ### 3. 匹配并执行验证
 
 执行统一验证入口：
 
+文末是通用入口示例；本技能的实际调用使用以下 validators 范围，不额外执行 review/e2e。
+
+- 有 active TASK 时走任务验证入口（`--checks` 等价于 `--layers validators`）：
+
+```bash
+code-flow task verify --checks --profile full --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+- 无 active TASK 或用户显式指定文件时走变更验证入口：
+
 ```bash
-python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
+code-flow validate --root "$PWD" --json
 ```
 
-显式范围追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；同一运行内相同 argv/cwd/timeout 去重，跨运行不复用。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
+仅 validators 支持任务进行中运行，不要求所有 TASK 完成，也不推进任务状态；active Context 损坏或身份不匹配仍阻断。`--profile full` 包含 heavy validator；只做轻量检查时明确使用 `--profile changed`。
+
+显式范围在 `code-flow validate` 后追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；通过结果按工作树内容指纹跨运行复用（失败永不缓存，需要强制重跑时使用 `code-flow validate --no-cache`），同一运行内相同 argv/cwd/timeout 去重。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
 
 ### 4. 汇总结果
 
@@ -63,7 +78,7 @@ python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
 
 ### 5. 自动修复
 
-对于失败的验证项，根据错误输出分析问题根因，自动尝试修复代码。修复后提示用户再次运行 `/project:cf-validate` 确认。
+对于失败的验证项，根据错误输出分析问题根因，自动尝试修复代码。修复后提示用户再次运行 `/cf-validate` 确认。
 
 ## 安全设计
 
@@ -77,3 +92,14 @@ python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
 - 命令执行超时 → 输出超时提示，建议增大 timeout 或缩小验证范围
 - 命令不存在或配置无效 → 返回 block 并提示所缺依赖，不当作验证通过
 - 无变更文件 → 输出"无变更需要验证"
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow validate --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->