@michaelxwb/code-flow 0.6.5 → 0.8.1

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

@@ -42,6 +42,9 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 - `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. 加载详设上下文
 
@@ -62,12 +65,12 @@ 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 不单独阻止激活；不新增阶段状态门禁。
+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`：
 
@@ -85,7 +88,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 失效。
@@ -106,20 +109,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 绕过验证。
+
+Done Gate 只执行 code 层验证；review 层 manual 规则与 manual 场景不逐任务确认，延后到需求级 verify-e2e（返回 `manual_confirmation_required` 时按该命令的「人工验收确认」流程一次性确认）。
 
-任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+验收断言失败时保持 `in-progress`；required code 检查未执行时由运行时转为 `provisional`。明确列出缺口，不能标记为 `done`。
 
 ### 5. 文档同步检查
 
@@ -193,7 +201,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
 ```
 
@@ -205,18 +213,19 @@ 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（.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>): <标题>"；
+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、遗留问题。
 ```
 
@@ -232,7 +241,7 @@ python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
 #### 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 已清理、有提交）。
@@ -241,35 +250,24 @@ python3 .code-flow/scripts/cf_task_parallel.py collect --root "$PWD" --run-id <r
 
 #### 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. 回到主工作区合并（此时应无冲突）：
+按 TASK-ID 先后顺序回并。统一入口自动完成：worktree 内 rebase → 状态文件冲突按确定性并集规则解决 → 主工作区 `--no-ff` 合并 → `code-flow spec refresh` 收敛 hash：
 
 ```bash
-git merge --no-ff -m "merge cf-task <TASK-ID>" <branch>
+code-flow task parallel merge --root "$PWD" --run-id <run_id> --json
 ```
 
-- 仍出现冲突（主区期间有新合并）：按双方意图解决并重跑双方 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 / 合并。
+- 返回 `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 由需求终验按证据缺口补验。
 
-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。
@@ -303,3 +301,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/codex/skills/cf-task-status/SKILL.md

@@ -3,6 +3,18 @@ name: cf-task-status
 description: "Show task status overview: subtask states, progress percentages, blocked items, and overall completion. Use when checking task progress, what's done, what's blocked, or what needs to be done next."
 ---
 
+## 命令面（0.8）
+
+`cf-task-status` 收敛了原先三个独立命令；旧命令保留一个 minor（0.9.0 移除）：
+
+| 子动作 | 等价旧命令 | 用途 |
+|--------|-----------|------|
+| `--notes` | `cf-task-note` | 讨论并收敛 `#NOTES` |
+| `--block` | `cf-task-block` | 标记阻塞并记录原因 |
+| `--graph` | `cf-task-graph` | 依赖 DAG 与并行批次 |
+
+带上述参数时，按对应旧命令章节的步骤执行；不带参数时行为不变。
+
 ## 输入
 
 - `cf-task-status` — 显示所有活跃 task 文件的状态

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

@@ -1,17 +1,30 @@
 ---
 name: cf-task-verify-e2e
-description: Execute deferred E2E scenarios after all functional tests pass
+description: Run layered verification or full requirement verification, including deferred 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 验收场景。
+
 ## 使用场景
 
 本命令是**需求级终验**入口，在所有子任务的 functional 测试通过后统一执行：
 
-1. **review 层 verifier**：绑定规范中 `stage: review` 的 required verifier（e2e/acceptance/构建等重型验证）。遍历需求目录全部 task context，按 spec/rule 去重执行一次，证据写回全部相关 context；输出 `executed` / `reused` / `failed` 计数。
-2. **E2E 验收场景**：依赖外部环境（数据库、API、浏览器等）、编码阶段标记 `e2e_deferred` 的场景。
+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 当成每个小改动的默认门禁。
+
 ## 调用方式
 
 ```
@@ -28,58 +41,69 @@ cf-task-verify-e2e <需求目录>
 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` 猜测端口、数据库或驱动，也不要固定询问环境是否就绪。
+
+收到 `env_blocked` 时，展示 `env_blocked_details` 中的 check ID、owner、失败的 preflight 命令、退出码和输出。根据真实失败修复可处理的本地问题；只有缺少外部配置、需要用户启动外部环境或涉及权限时请求用户输入。未声明 preflight 的检查仍按真实执行结果判断，不能自报环境已通过。
 
-- `HTTP API` → 提示确认 API 服务运行中
-- `Browser` → 提示确认浏览器驱动已安装
-- `Database` → 提示确认测试数据库可访问
+### 3. 执行 E2E 场景
 
-显示清单并询问：
+用户请求需求级终验时，执行：
 
+```bash
+code-flow task verify \
+  --task-dir "<需求目录>" --root "$PWD" \
+  --layers validators,review,e2e --profile full --json
 ```
-E2E 场景需要以下环境：
-  - 本地 API 服务 (http://localhost:3000)
-  - PostgreSQL 测试数据库
-  - Chrome WebDriver
 
-环境已就绪？(y/N)
-```
+相关批次使用 `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`。
 
-### 3. 执行 E2E 场景
+全量终验重新检查所有 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`，并保留原契约与运行历史。其他验证范围保留原状态。无需再次编辑状态。
 
 ## 失败处理
 
@@ -87,7 +111,7 @@ E2E 失败时：
 
 1. 显示失败场景的完整命令和退出码
 2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
-3. 不自动修改任务状态，等待用户修复后重新执行
+3. 修复可处理的问题后重跑所选范围；缺少用户输入时报告具体阻塞，不自动修改任务状态
 
 ## 示例
 
@@ -96,11 +120,7 @@ cf-task-verify-e2e .code-flow/tasks/2026-03-15/auth-module
 
 > 检查子任务状态... 所有任务已完成
 > 
-> E2E 场景需要以下环境：
->   - 本地 API 服务 (http://localhost:3000)
->   - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
-> 
-> 环境已就绪？(y/N) y
+> 按 checks 声明执行 preflight... 通过
 > 
 > 执行 E2E 场景...
 >   ✓ E-01: 用户登录流程 (1.2s)
@@ -109,3 +129,17 @@ cf-task-verify-e2e .code-flow/tasks/2026-03-15/auth-module
 > 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/codex/skills/cf-validate/SKILL.md

@@ -3,6 +3,9 @@ name: cf-validate
 description: Run validation rules (lint, type check, tests) against changed files based on .code-flow/validation.yml. Auto-fix failures. Use when validating code changes, running project checks, or after editing source files.
 ---
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-verify-e2e --checks`（运行时 `code-flow task verify --checks`）；保留一个 minor，0.9.0 移除。
+
+
 ## 输入
 
 - `cf-validate` — 自动获取任务基线或 Git 全部变更文件
@@ -16,7 +19,7 @@ description: Run validation rules (lint, type check, tests) against changed file
 用 shell 命令执行：
 
 ```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"` 原样传递；若结果确实为空才输出“无变更需要验证”。
@@ -33,21 +36,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. 汇总结果
 
@@ -74,3 +89,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 -->

package/src/adapters/commands.json

@@ -0,0 +1,115 @@
+{
+  "schema_version": 1,
+  "content_canonical": "claude",
+  "commands": [
+    {
+      "id": "cf-init",
+      "file": "cf-init.md",
+      "kind": "user",
+      "description": "初始化项目规范体系"
+    },
+    {
+      "id": "cf-learn",
+      "file": "cf-learn.md",
+      "kind": "user",
+      "description": "从项目证据沉淀规范"
+    },
+    {
+      "id": "cf-spec",
+      "file": "cf-spec.md",
+      "kind": "user",
+      "description": "Spec Context、迁移计划与 doctor"
+    },
+    {
+      "id": "cf-stats",
+      "file": "cf-stats.md",
+      "kind": "user",
+      "description": "Token/预算统计与规范质量审计"
+    },
+    {
+      "id": "cf-task-prd",
+      "file": "cf-task/prd.md",
+      "kind": "user",
+      "description": "产出产品需求文档"
+    },
+    {
+      "id": "cf-task-align",
+      "file": "cf-task/align.md",
+      "kind": "user",
+      "description": "需求对齐与设计简报"
+    },
+    {
+      "id": "cf-task-plan",
+      "file": "cf-task/plan.md",
+      "kind": "user",
+      "description": "能力级任务拆解与预算门禁"
+    },
+    {
+      "id": "cf-task-start",
+      "file": "cf-task/start.md",
+      "kind": "user",
+      "description": "激活任务并编码"
+    },
+    {
+      "id": "cf-task-status",
+      "file": "cf-task/status.md",
+      "kind": "user",
+      "description": "任务状态总览与 notes/block/graph 子动作",
+      "subactions": [
+        "--notes",
+        "--block",
+        "--graph"
+      ]
+    },
+    {
+      "id": "cf-task-archive",
+      "file": "cf-task/archive.md",
+      "kind": "user",
+      "description": "归档已完成需求"
+    },
+    {
+      "id": "cf-task-verify-e2e",
+      "file": "cf-task/verify-e2e.md",
+      "kind": "user",
+      "description": "分层/分级验证（task verify 别名）"
+    },
+    {
+      "id": "cf-task-note",
+      "file": "cf-task/note.md",
+      "kind": "alias",
+      "alias_of": "cf-task-status",
+      "alias_flag": "--notes",
+      "remove_in": "0.9.0"
+    },
+    {
+      "id": "cf-task-block",
+      "file": "cf-task/block.md",
+      "kind": "alias",
+      "alias_of": "cf-task-status",
+      "alias_flag": "--block",
+      "remove_in": "0.9.0"
+    },
+    {
+      "id": "cf-task-graph",
+      "file": "cf-task/graph.md",
+      "kind": "alias",
+      "alias_of": "cf-task-status",
+      "alias_flag": "--graph",
+      "remove_in": "0.9.0"
+    },
+    {
+      "id": "cf-validate",
+      "file": "cf-validate.md",
+      "kind": "alias",
+      "alias_of": "cf-task-verify-e2e",
+      "alias_flag": "--checks",
+      "remove_in": "0.9.0"
+    },
+    {
+      "id": "cf-sync",
+      "file": "cf-sync.md",
+      "kind": "internal",
+      "description": "canonical → 部署副本同步，仅开发/发布维护使用"
+    }
+  ]
+}

package/src/adapters/costrict/CLAUDE.md

@@ -32,7 +32,7 @@ Do NOT ask the user which Specs to load—the Context-first router is authoritat
 
 1. 编辑代码后收到 **Spec 合规反馈 (auto-check)** 时，先按提示修正违规，再继续当前任务
 2. 用户表示某条反馈是误报（"这是误报"/"忽略这个检查"）时，代为执行：
-   `python3 .code-flow/scripts/cf_feedback.py ignore <check-id>`
+   `code-flow feedback ignore <check-id>`
    （check-id 见反馈中的 `规则: <spec>#<check-id>`；同一规则误报达阈值会自动停用）
 3. 会话收尾被校验拦回（cf-stop 反馈未过项）时，修复后再结束；不要绕过
 4. 新增/修改规范时优先用 ✅/❌ 代码对照示例表达（见 spec 模板 Examples 段）

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

@@ -153,9 +153,7 @@ CLAUDE.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 .costrict/settings.local.json Hook 配置
 
-检查 `.costrict/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 hook，并使用 guarded project root 定位脚本路径。
-
-如果文件已存在，只合并缺失的 hook 事件、matcher 或 command，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。
+执行 `code-flow init --platform=costrict`，由适配器模板统一生成/合并 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 Hook，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。不得手工拼装受管理 Hook；旧安装或清单校验失败时通过 `code-flow migrate --runtime --dry-run` / `--apply` 修复。
 
 ### 7. 安装 pyyaml
 

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

@@ -31,7 +31,7 @@
 
 1. 读取并展示 `spec-context.yml` 的 bindings、Rule stage status、artifact refs、Evidence 与 drift。
 2. 执行：
-   `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
+   `code-flow spec validate --task-dir <目录> --json`
 3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
 
 
@@ -41,7 +41,7 @@
 
 执行：
 
-`python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
+`code-flow spec status --task-dir <目录> --root "$PWD"`
 
 - marker 漂移时输出下一步：先 refresh 自动重同步；仍不一致时用 `active doctor --resync`（hash 取 status --json 的 context_sha256）。
 - 需要机器可读输出时加 `--json`。
@@ -50,7 +50,7 @@
 
 执行：
 
-`python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <目录> --root "$PWD" --json`
+`code-flow spec refresh --task-dir <目录> --root "$PWD" --json`
 
 - changed required Rule 标为 stale，关联 stage Gate 必须阻断。
 - missing/conflict 不自动降级；回 Align 或 Plan 更新承接后再继续。
@@ -65,3 +65,23 @@
    - **marker 损坏或归属无法证明**：向用户说明影响，仅在用户明确确认放弃该 TASK 后执行 `active doctor --abandon`，随后重新规划该任务。
 3. `active doctor` 返回 `recovery_required`（退出码 3）是诊断结果而非崩溃：按第 2 步选择 refresh / `--resync` / `--abandon`，不要用 `--help` 探测或反复重试。
 4. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。
+5. doctor 的安装/Context 健康结果与 `readiness.plan/code/review` 分开阅读。`applied` 只表示存在引用，不能替代 code/review 的 verified 执行证据；引用条目仍有“待同步/待确认/TBD”时返回 `rule_applied_unresolved`。
+6. `decision=null` 是自动验证的正常情况；无需改代码但已符合规则时提交对应证据，不强制用户 N/A。只有确实不适用/豁免时要求用户 decision。
+7. `convention_review_required` 表示绑定 Spec 的 Conventions 尚未成为可执行约束；审查与当前设计的冲突，关键条目提升为稳定 Rule 并配置 verifier。CLI 低于 runtime 时先按提示升级 CLI；不要尝试把项目 runtime 降级。
+
+## 规范自检与优化
+
+按 `docs/spec-optimization.md` 执行审计、路径预算、影响查询和只读优化预览。`code-flow spec optimize --apply --plan <提案>` 需要在交互终端展示并获得用户对具体 diff 的明确确认；不得代为确认。应用后对受影响需求执行 refresh 和 doctor。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec optimize --help
+code-flow spec validate --task-dir "<需求目录>" --json
+code-flow spec status --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->