@michaelxwb/code-flow 0.6.2 → 0.6.3

package/package.json

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

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

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

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

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

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

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

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

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

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

@@ -22,8 +22,8 @@
 用 Read 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
-- `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
+- `in-progress` → 校验现有 marker 的需求目录、TASK-ID 与 Context；匹配且为 active 才继续步骤 2，跳过重复 Start。paused/blocked 先解除原因并调用 resume；marker 缺失或不匹配先 doctor，不能仅改 Markdown。
+- `done` / `verified` → 实现已完成；done 的 E2E 可为 e2e_deferred，转 verify-e2e 终验。发现缺口时报告并显式重新规划修复任务，不直接把终态改成 in-progress。
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -32,7 +32,7 @@
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
-- 所有依赖必须为 `done`
+- 所有依赖必须为 `done` 或 `verified`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
 **验收契约检查**：
@@ -60,9 +60,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/pending/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
-3. 只有前两步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
+3. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
 4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
 5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
 6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
@@ -83,11 +83,10 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
-2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
-3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
-4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
-5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
+1. 执行 functional 验收和受影响范围的回归测试；E2E 已在编码前锁定场景、断言、真实边界和命令，完整 GREEN 留给 verify-e2e。
+2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
+3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
+4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
 
 ### 3.5 TASK-bound Spec Session
 
@@ -105,16 +104,18 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
 - `manual` 场景已有用户确认和可复核记录
 
-满足后：
-1. 用 Edit 更新 Status 为 `done`
-2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
-3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成`
+满足后，执行唯一收尾入口：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -23,8 +23,8 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
-- `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
+- `in-progress` → 校验现有 marker 的需求目录、TASK-ID 与 Context；匹配且为 active 才继续步骤 2，跳过重复 Start。paused/blocked 先解除原因并调用 resume；marker 缺失或不匹配先 doctor，不能仅改 Markdown。
+- `done` / `verified` → 实现已完成；done 的 E2E 可为 e2e_deferred，转 verify-e2e 终验。发现缺口时报告并显式重新规划修复任务，不直接把终态改成 in-progress。
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -33,7 +33,7 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
-- 所有依赖必须为 `done`
+- 所有依赖必须为 `done` 或 `verified`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
 **验收契约检查**：
@@ -61,9 +61,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/pending/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
-3. 只有前两步全部成功，才用 apply_patch 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
+3. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
 4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
 5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
 6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
@@ -84,11 +84,10 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
-2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
-3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
-4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
-5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
+1. 执行 functional 验收和受影响范围的回归测试；E2E 已在编码前锁定场景、断言、真实边界和命令，完整 GREEN 留给 verify-e2e。
+2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
+3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
+4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
 
 ### 3.5 TASK-bound Spec Session
 
@@ -106,16 +105,18 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
 - `manual` 场景已有用户确认和可复核记录
 
-满足后：
-1. 用 apply_patch 更新 Status 为 `done`
-2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
-3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成`
+满足后，执行唯一收尾入口：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 

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

@@ -0,0 +1,106 @@
+---
+name: cf-task-verify-e2e
+description: Execute deferred E2E scenarios after all functional tests pass
+---
+
+## 使用场景
+
+E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+
+## 调用方式
+
+```
+cf-task-verify-e2e <需求目录>
+```
+
+## 执行步骤
+
+### 1. 检查前置条件
+
+确认需求目录下所有子任务状态为 `done`（实现完成）或 `verified`（终验已闭环）：
+
+```bash
+rg "^- \*\*Status\*\*:" <需求目录>/*.md
+```
+
+如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
+
+### 2. 检查环境依赖
+
+读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
+
+- `HTTP API` → 提示确认 API 服务运行中
+- `Browser` → 提示确认浏览器驱动已安装
+- `Database` → 提示确认测试数据库可访问
+
+显示清单并询问：
+
+```
+E2E 场景需要以下环境：
+  - 本地 API 服务 (http://localhost:3000)
+  - PostgreSQL 测试数据库
+  - Chrome WebDriver
+
+环境已就绪？(y/N)
+```
+
+### 3. 执行 E2E 场景
+
+用户确认后，执行：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py verify-e2e \
+  --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+该入口重新检查所有 TASK、锁定 manifest 和 functional/manual 最新证据，内部以 `--only-e2e` 调用 runner；只有全通过才把任务提升为 verified。不得手动改状态。
+
+### 4. 报告结果
+
+解析执行结果：
+
+```json
+{
+  "decision": "block",
+  "results": [
+    {"id": "E-01", "kind": "e2e", "status": "passed"},
+    {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
+  ]
+}
+```
+
+- `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
+- `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
+
+### 5. 更新任务状态
+
+确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
+
+## 失败处理
+
+E2E 失败时：
+
+1. 显示失败场景的完整命令和退出码
+2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
+3. 不自动修改任务状态，等待用户修复后重新执行
+
+## 示例
+
+```
+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
+> 
+> 执行 E2E 场景...
+>   ✓ E-01: 用户登录流程 (1.2s)
+>   ✓ E-02: 权限验证链路 (0.8s)
+> 
+> E2E 验收完成！2/2 场景通过
+> 已更新任务状态为 verified
+```