@michaelxwb/code-flow 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/package.json +1 -1
  2. package/src/adapters/claude/commands/cf-spec.md +13 -0
  3. package/src/adapters/claude/commands/cf-sync.md +25 -0
  4. package/src/adapters/claude/commands/cf-task/plan.md +40 -0
  5. package/src/adapters/claude/commands/cf-task/start.md +6 -7
  6. package/src/adapters/claude/commands/cf-task/verify-e2e.md +111 -0
  7. package/src/adapters/codex/skills/cf-spec/SKILL.md +1 -0
  8. package/src/adapters/codex/skills/cf-sync/SKILL.md +30 -0
  9. package/src/adapters/codex/skills/cf-task-start/SKILL.md +6 -7
  10. package/src/adapters/costrict/commands/cf-spec.md +13 -0
  11. package/src/adapters/costrict/commands/cf-sync.md +25 -0
  12. package/src/adapters/costrict/commands/cf-task/plan.md +40 -0
  13. package/src/adapters/costrict/commands/cf-task/start.md +6 -7
  14. package/src/adapters/costrict/commands/cf-task/verify-e2e.md +111 -0
  15. package/src/adapters/opencode/commands/cf-spec.md +1 -0
  16. package/src/adapters/opencode/commands/cf-sync.md +29 -0
  17. package/src/adapters/opencode/commands/cf-task/plan.md +40 -5
  18. package/src/adapters/opencode/commands/cf-task/start.md +6 -7
  19. package/src/adapters/opencode/commands/cf-task/verify-e2e.md +111 -0
  20. package/src/adapters/opencode/plugins/code-flow/index.js +3 -3
  21. package/src/core/code-flow/config.yml +2 -1
  22. package/src/core/code-flow/scripts/cf_acceptance_manifest.py +199 -0
  23. package/src/core/code-flow/scripts/cf_acceptance_runner.py +107 -0
  24. package/src/core/code-flow/scripts/cf_core.py +44 -1
  25. package/src/core/code-flow/scripts/cf_post_hook.py +5 -30
  26. package/src/core/code-flow/scripts/cf_pre_tool_hook.py +41 -17
  27. package/src/core/code-flow/scripts/cf_session_state.py +37 -0
  28. package/src/core/code-flow/scripts/cf_spec_context.py +381 -29
  29. package/src/core/code-flow/scripts/cf_spec_gate.py +22 -6
  30. package/src/core/code-flow/scripts/cf_spec_metadata.py +60 -11
  31. package/src/core/code-flow/scripts/cf_spec_resolver.py +78 -7
  32. package/src/core/code-flow/scripts/cf_spec_router.py +107 -10
  33. package/src/core/code-flow/scripts/cf_spec_session.py +5 -9
  34. package/src/core/code-flow/scripts/cf_spec_verify.py +166 -9
  35. package/src/core/code-flow/scripts/cf_stop_hook.py +35 -12
  36. package/src/core/code-flow/scripts/cf_sync.py +140 -0
  37. package/src/core/code-flow/scripts/cf_task_runtime.py +95 -7
  38. package/src/core/code-flow/scripts/cf_user_prompt_hook.py +106 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@michaelxwb/code-flow",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "license": "UNLICENSED",
5
5
  "bin": {
6
6
  "code-flow": "src/cli.js"
package/src/adapters/claude/commands/cf-spec.md CHANGED
@@ -5,6 +5,7 @@
5
5
  - `cf-spec migrate --plan <migration-plan.yml>`
6
6
  - `cf-spec context [需求目录]`
7
7
  - `cf-spec refresh [需求目录]`
8
+ - `cf-spec status [需求目录]`
8
9
  - `cf-spec doctor [需求目录]`
9
10
 
10
11
  ## 通用硬门禁
@@ -33,6 +34,18 @@
33
34
  `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
34
35
  3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
35
36
 
37
+
38
+ ## status
39
+
40
+ 展示人话版 Context 状态：任务、marker hash 是否一致、code Gate 结果、各绑定 Rule 状态。
41
+
42
+ 执行：
43
+
44
+ `python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
45
+
46
+ - marker 漂移时输出下一步（cf-spec doctor resync）。
47
+ - 需要机器可读输出时加 `--json`。
48
+
36
49
  ## refresh
37
50
 
38
51
  执行：
package/src/adapters/claude/commands/cf-sync.md ADDED
@@ -0,0 +1,25 @@
1
+ # cf-sync
2
+
3
+ 一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
4
+
5
+ - `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
6
+ - `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
7
+ - `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
8
+
9
+ ## 同步配对
10
+
11
+ | canonical 源 | 部署副本 | 同步内容 |
12
+ |---|---|---|
13
+ | `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
14
+ | `src/adapters/claude` | `.claude` | `commands/` |
15
+ | `src/adapters/codex` | `.codex` | `hooks.json` |
16
+ | `src/adapters/codex/skills` | `.agents/skills` | 全部 |
17
+ | `src/adapters/costrict` | `.costrict` | `commands/` |
18
+ | `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
19
+
20
+ ## 规则
21
+
22
+ 1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
23
+ 2. 部署侧独有文件不会被删除（避免误删本地产物）。
24
+ 3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
25
+ 4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。
package/src/adapters/claude/commands/cf-task/plan.md CHANGED
@@ -8,6 +8,8 @@
8
8
  - `/cf-task:plan` — 交互式选择（从 `docs/` 目录列出候选）
9
9
  - `/cf-task:plan <设计文档路径> --explore` — 仅输出分析报告，不生成文件
10
10
  - `/cf-task:plan <设计文档路径> --quick` — 跳过缺口分析，直接拆解（保持原有行为）
11
+ - `/cf-task:plan <设计文档路径> --draft` — 仅生成任务草案，必须经过 `--verify-plan` 后才能启动
12
+ - `/cf-task:plan <任务文件> --verify-plan` — 执行完整 Acceptance Coverage 与 Spec Rule 门禁
11
13
  - `/cf-task:plan <.design.md 路径>` — 从 cf-task:align 产出的设计简报拆解（自动跳过缺口分析）
12
14
 
13
15
  ## 执行步骤
@@ -57,6 +59,17 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
57
59
 
58
60
  此索引用于后续步骤中精确记录每个子任务的来源章节。
59
61
 
62
+ ### 2.4.1. Draft / Verify Plan 模式
63
+
64
+ `--draft` 只生成任务结构、依赖、Source 和初步验收映射，产物状态必须保持 `draft`，不得直接进入 `start`。用户确认拆分后执行 `--verify-plan`，完成全部场景覆盖、唯一 Rule owner、verifier、测试层级和真实边界校验；默认模式仍执行完整校验。
65
+
66
+ `--verify-plan` 的执行命令为：
67
+
68
+ ```bash
69
+ python3 .code-flow/scripts/cf_acceptance_manifest.py \
70
+ --verify-plan --task-dir <需求目录> --task-file <任务文件>
71
+ ```
72
+
60
73
  ### 2.5. Explore 模式（--explore）
61
74
 
62
75
  如果用户传入 `--explore`，在建立章节索引后，输出以下分析报告，**不生成任务文件**：
@@ -298,6 +311,33 @@ TASK-002: <标题> [P1]
298
311
  python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
299
312
  ```
300
313
 
314
+ 通过 Plan Gate 后，锁定验收基线：
315
+
316
+ ```bash
317
+ python3 .code-flow/scripts/cf_acceptance_manifest.py \
318
+ --task-file <任务文件> \
319
+ --output <需求目录>/.acceptance-manifest.json
320
+ ```
321
+
322
+ Manifest 锁定场景 ID、来源、测试层级、真实边界和责任 TASK。编码阶段不得静默修改这些字段；如发生范围变化，必须重新执行 plan 验证。
323
+
324
+ 验收类型按测试层级归类：
325
+ - `unit/integration` → `functional`（Done Gate 自动执行）
326
+ - `E2E` → `e2e`（延迟至所有任务完成后，需 `--include-e2e` 显式执行）
327
+ - `manual` → `manual`（用户手动验证，永不自动执行）
328
+
329
+ E2E 场景依赖外部环境（数据库、API、浏览器），在编码阶段默认跳过（状态 `e2e_deferred`），不阻断 Done Gate。所有子任务完成后，执行：
330
+
331
+ ```bash
332
+ python3 .code-flow/scripts/cf_acceptance_runner.py \
333
+ --manifest <需求目录>/.acceptance-manifest.json \
334
+ --root . \
335
+ --include-e2e \
336
+ --write-evidence
337
+ ```
338
+
339
+ 不得为了提速降低 design 指定的 E2E 层级。
340
+
301
341
  只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
302
342
 
303
343
  ### 6. 输出摘要
package/src/adapters/claude/commands/cf-task/start.md CHANGED
@@ -60,13 +60,12 @@
60
60
 
61
61
  在改状态或生产代码前，顺序固定且不得跳步：
62
62
 
63
- 1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
64
- 2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
65
- 3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
66
- 4. 只有前三步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
67
- 5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
68
- 6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
69
- 7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
63
+ 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 在编码前自行漂移。
64
+ 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
65
+ 3. 只有前两步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
66
+ 4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
67
+ 5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
68
+ 6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
70
69
 
71
70
  RED 证据写入 `Acceptance Evidence`：
72
71
 
package/src/adapters/claude/commands/cf-task/verify-e2e.md ADDED
@@ -0,0 +1,111 @@
1
+ ---
2
+ description: Execute deferred E2E scenarios after all functional tests pass
3
+ globs: []
4
+ ---
5
+
6
+ # cf-task:verify-e2e
7
+
8
+ 执行需求目录下被延迟的 E2E 验收场景。
9
+
10
+ ## 使用场景
11
+
12
+ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
13
+
14
+ ## 调用方式
15
+
16
+ ```
17
+ /cf-task:verify-e2e <需求目录>
18
+ ```
19
+
20
+ ## 执行步骤
21
+
22
+ ### 1. 检查前置条件
23
+
24
+ 确认需求目录下所有子任务状态为 `done` 或 `verified`：
25
+
26
+ ```bash
27
+ rg "^Status:" <需求目录>/*.md
28
+ ```
29
+
30
+ 如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
31
+
32
+ ### 2. 检查环境依赖
33
+
34
+ 读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
35
+
36
+ - `HTTP API` → 提示确认 API 服务运行中
37
+ - `Browser` → 提示确认浏览器驱动已安装
38
+ - `Database` → 提示确认测试数据库可访问
39
+
40
+ 显示清单并询问：
41
+
42
+ ```
43
+ E2E 场景需要以下环境：
44
+ - 本地 API 服务 (http://localhost:3000)
45
+ - PostgreSQL 测试数据库
46
+ - Chrome WebDriver
47
+
48
+ 环境已就绪？(y/N)
49
+ ```
50
+
51
+ ### 3. 执行 E2E 场景
52
+
53
+ 用户确认后，执行：
54
+
55
+ ```bash
56
+ python3 .code-flow/scripts/cf_acceptance_runner.py \
57
+ --manifest <需求目录>/.acceptance-manifest.json \
58
+ --root . \
59
+ --include-e2e \
60
+ --write-evidence
61
+ ```
62
+
63
+ ### 4. 报告结果
64
+
65
+ 解析执行结果：
66
+
67
+ ```json
68
+ {
69
+ "decision": "pass",
70
+ "results": [
71
+ {"id": "E-01", "kind": "e2e", "status": "passed"},
72
+ {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
73
+ ]
74
+ }
75
+ ```
76
+
77
+ - `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
78
+ - `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
79
+
80
+ ### 5. 更新任务状态
81
+
82
+ 所有 E2E 通过后，将需求目录下的任务状态更新为 `verified`（如果当前是 `done`）。
83
+
84
+ ## 失败处理
85
+
86
+ E2E 失败时：
87
+
88
+ 1. 显示失败场景的完整命令和退出码
89
+ 2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
90
+ 3. 不自动修改任务状态，等待用户修复后重新执行
91
+
92
+ ## 示例
93
+
94
+ ```
95
+ /cf-task:verify-e2e .code-flow/tasks/2026-03-15/auth-module
96
+
97
+ > 检查子任务状态... 所有任务已完成
98
+ >
99
+ > E2E 场景需要以下环境：
100
+ > - 本地 API 服务 (http://localhost:3000)
101
+ > - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
102
+ >
103
+ > 环境已就绪？(y/N) y
104
+ >
105
+ > 执行 E2E 场景...
106
+ > ✓ E-01: 用户登录流程 (1.2s)
107
+ > ✓ E-02: 权限验证链路 (0.8s)
108
+ >
109
+ > E2E 验收完成！2/2 场景通过
110
+ > 已更新任务状态为 verified
111
+ ```
package/src/adapters/codex/skills/cf-spec/SKILL.md CHANGED
@@ -10,6 +10,7 @@ description: Manage schema-v1 Spec Context, drift recovery, and prepared one-sho
10
10
  - `cf-spec migrate --plan <migration-plan.yml>`
11
11
  - `cf-spec context [需求目录]`
12
12
  - `cf-spec refresh [需求目录]`
13
+ - `cf-spec status [需求目录]`
13
14
  - `cf-spec doctor [需求目录]`
14
15
 
15
16
  ## 通用硬门禁
package/src/adapters/codex/skills/cf-sync/SKILL.md ADDED
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: cf-sync
3
+ description: One-command canonical → deploy sync for dual-copy artifacts, with drift check.
4
+ ---
5
+
6
+ # cf-sync
7
+
8
+ 一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
9
+
10
+ - `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
11
+ - `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
12
+ - `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
13
+
14
+ ## 同步配对
15
+
16
+ | canonical 源 | 部署副本 | 同步内容 |
17
+ |---|---|---|
18
+ | `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
19
+ | `src/adapters/claude` | `.claude` | `commands/` |
20
+ | `src/adapters/codex` | `.codex` | `hooks.json` |
21
+ | `src/adapters/codex/skills` | `.agents/skills` | 全部 |
22
+ | `src/adapters/costrict` | `.costrict` | `commands/` |
23
+ | `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
24
+
25
+ ## 规则
26
+
27
+ 1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
28
+ 2. 部署侧独有文件不会被删除（避免误删本地产物）。
29
+ 3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
30
+ 4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。
package/src/adapters/codex/skills/cf-task-start/SKILL.md CHANGED
@@ -61,13 +61,12 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
61
61
 
62
62
  在改状态或生产代码前，顺序固定且不得跳步：
63
63
 
64
- 1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
65
- 2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
66
- 3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
67
- 4. 只有前三步全部成功，才用 apply_patch 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
68
- 5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
69
- 6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
70
- 7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
64
+ 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 在编码前自行漂移。
65
+ 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
66
+ 3. 只有前两步全部成功，才用 apply_patch 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
67
+ 4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
68
+ 5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
69
+ 6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
71
70
 
72
71
  RED 证据写入 `Acceptance Evidence`：
73
72
 
package/src/adapters/costrict/commands/cf-spec.md CHANGED
@@ -5,6 +5,7 @@
5
5
  - `cf-spec migrate --plan <migration-plan.yml>`
6
6
  - `cf-spec context [需求目录]`
7
7
  - `cf-spec refresh [需求目录]`
8
+ - `cf-spec status [需求目录]`
8
9
  - `cf-spec doctor [需求目录]`
9
10
 
10
11
  ## 通用硬门禁
@@ -33,6 +34,18 @@
33
34
  `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
34
35
  3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
35
36
 
37
+
38
+ ## status
39
+
40
+ 展示人话版 Context 状态：任务、marker hash 是否一致、code Gate 结果、各绑定 Rule 状态。
41
+
42
+ 执行：
43
+
44
+ `python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
45
+
46
+ - marker 漂移时输出下一步（cf-spec doctor resync）。
47
+ - 需要机器可读输出时加 `--json`。
48
+
36
49
  ## refresh
37
50
 
38
51
  执行：
package/src/adapters/costrict/commands/cf-sync.md ADDED
@@ -0,0 +1,25 @@
1
+ # cf-sync
2
+
3
+ 一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
4
+
5
+ - `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
6
+ - `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
7
+ - `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
8
+
9
+ ## 同步配对
10
+
11
+ | canonical 源 | 部署副本 | 同步内容 |
12
+ |---|---|---|
13
+ | `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
14
+ | `src/adapters/claude` | `.claude` | `commands/` |
15
+ | `src/adapters/codex` | `.codex` | `hooks.json` |
16
+ | `src/adapters/codex/skills` | `.agents/skills` | 全部 |
17
+ | `src/adapters/costrict` | `.costrict` | `commands/` |
18
+ | `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
19
+
20
+ ## 规则
21
+
22
+ 1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
23
+ 2. 部署侧独有文件不会被删除（避免误删本地产物）。
24
+ 3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
25
+ 4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。
package/src/adapters/costrict/commands/cf-task/plan.md CHANGED
@@ -8,6 +8,8 @@
8
8
  - `/cf-task:plan` — 交互式选择（从 `docs/` 目录列出候选）
9
9
  - `/cf-task:plan <设计文档路径> --explore` — 仅输出分析报告，不生成文件
10
10
  - `/cf-task:plan <设计文档路径> --quick` — 跳过缺口分析，直接拆解（保持原有行为）
11
+ - `/cf-task:plan <设计文档路径> --draft` — 仅生成任务草案，必须经过 `--verify-plan` 后才能启动
12
+ - `/cf-task:plan <任务文件> --verify-plan` — 执行完整 Acceptance Coverage 与 Spec Rule 门禁
11
13
  - `/cf-task:plan <.design.md 路径>` — 从 cf-task:align 产出的设计简报拆解（自动跳过缺口分析）
12
14
 
13
15
  ## 执行步骤
@@ -57,6 +59,17 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
57
59
 
58
60
  此索引用于后续步骤中精确记录每个子任务的来源章节。
59
61
 
62
+ ### 2.4.1. Draft / Verify Plan 模式
63
+
64
+ `--draft` 只生成任务结构、依赖、Source 和初步验收映射，产物状态必须保持 `draft`，不得直接进入 `start`。用户确认拆分后执行 `--verify-plan`，完成全部场景覆盖、唯一 Rule owner、verifier、测试层级和真实边界校验；默认模式仍执行完整校验。
65
+
66
+ `--verify-plan` 的执行命令为：
67
+
68
+ ```bash
69
+ python3 .code-flow/scripts/cf_acceptance_manifest.py \
70
+ --verify-plan --task-dir <需求目录> --task-file <任务文件>
71
+ ```
72
+
60
73
  ### 2.5. Explore 模式（--explore）
61
74
 
62
75
  如果用户传入 `--explore`，在建立章节索引后，输出以下分析报告，**不生成任务文件**：
@@ -298,6 +311,33 @@ TASK-002: <标题> [P1]
298
311
  python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
299
312
  ```
300
313
 
314
+ 通过 Plan Gate 后，锁定验收基线：
315
+
316
+ ```bash
317
+ python3 .code-flow/scripts/cf_acceptance_manifest.py \
318
+ --task-file <任务文件> \
319
+ --output <需求目录>/.acceptance-manifest.json
320
+ ```
321
+
322
+ Manifest 锁定场景 ID、来源、测试层级、真实边界和责任 TASK。编码阶段不得静默修改这些字段；如发生范围变化，必须重新执行 plan 验证。
323
+
324
+ 验收类型按测试层级归类：
325
+ - `unit/integration` → `functional`（Done Gate 自动执行）
326
+ - `E2E` → `e2e`（延迟至所有任务完成后，需 `--include-e2e` 显式执行）
327
+ - `manual` → `manual`（用户手动验证，永不自动执行）
328
+
329
+ E2E 场景依赖外部环境（数据库、API、浏览器），在编码阶段默认跳过（状态 `e2e_deferred`），不阻断 Done Gate。所有子任务完成后，执行：
330
+
331
+ ```bash
332
+ python3 .code-flow/scripts/cf_acceptance_runner.py \
333
+ --manifest <需求目录>/.acceptance-manifest.json \
334
+ --root . \
335
+ --include-e2e \
336
+ --write-evidence
337
+ ```
338
+
339
+ 不得为了提速降低 design 指定的 E2E 层级。
340
+
301
341
  只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
302
342
 
303
343
  ### 6. 输出摘要
package/src/adapters/costrict/commands/cf-task/start.md CHANGED
@@ -60,13 +60,12 @@
60
60
 
61
61
  在改状态或生产代码前，顺序固定且不得跳步：
62
62
 
63
- 1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
64
- 2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
65
- 3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
66
- 4. 只有前三步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
67
- 5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
68
- 6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
69
- 7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
63
+ 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 在编码前自行漂移。
64
+ 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
65
+ 3. 只有前两步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
66
+ 4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
67
+ 5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
68
+ 6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
70
69
 
71
70
  RED 证据写入 `Acceptance Evidence`：
72
71
 
package/src/adapters/costrict/commands/cf-task/verify-e2e.md ADDED
@@ -0,0 +1,111 @@
1
+ ---
2
+ description: Execute deferred E2E scenarios after all functional tests pass
3
+ globs: []
4
+ ---
5
+
6
+ # cf-task:verify-e2e
7
+
8
+ 执行需求目录下被延迟的 E2E 验收场景。
9
+
10
+ ## 使用场景
11
+
12
+ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
13
+
14
+ ## 调用方式
15
+
16
+ ```
17
+ /cf-task:verify-e2e <需求目录>
18
+ ```
19
+
20
+ ## 执行步骤
21
+
22
+ ### 1. 检查前置条件
23
+
24
+ 确认需求目录下所有子任务状态为 `done` 或 `verified`：
25
+
26
+ ```bash
27
+ rg "^Status:" <需求目录>/*.md
28
+ ```
29
+
30
+ 如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
31
+
32
+ ### 2. 检查环境依赖
33
+
34
+ 读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
35
+
36
+ - `HTTP API` → 提示确认 API 服务运行中
37
+ - `Browser` → 提示确认浏览器驱动已安装
38
+ - `Database` → 提示确认测试数据库可访问
39
+
40
+ 显示清单并询问：
41
+
42
+ ```
43
+ E2E 场景需要以下环境：
44
+ - 本地 API 服务 (http://localhost:3000)
45
+ - PostgreSQL 测试数据库
46
+ - Chrome WebDriver
47
+
48
+ 环境已就绪？(y/N)
49
+ ```
50
+
51
+ ### 3. 执行 E2E 场景
52
+
53
+ 用户确认后，执行：
54
+
55
+ ```bash
56
+ python3 .code-flow/scripts/cf_acceptance_runner.py \
57
+ --manifest <需求目录>/.acceptance-manifest.json \
58
+ --root . \
59
+ --include-e2e \
60
+ --write-evidence
61
+ ```
62
+
63
+ ### 4. 报告结果
64
+
65
+ 解析执行结果：
66
+
67
+ ```json
68
+ {
69
+ "decision": "pass",
70
+ "results": [
71
+ {"id": "E-01", "kind": "e2e", "status": "passed"},
72
+ {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
73
+ ]
74
+ }
75
+ ```
76
+
77
+ - `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
78
+ - `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
79
+
80
+ ### 5. 更新任务状态
81
+
82
+ 所有 E2E 通过后，将需求目录下的任务状态更新为 `verified`（如果当前是 `done`）。
83
+
84
+ ## 失败处理
85
+
86
+ E2E 失败时：
87
+
88
+ 1. 显示失败场景的完整命令和退出码
89
+ 2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
90
+ 3. 不自动修改任务状态，等待用户修复后重新执行
91
+
92
+ ## 示例
93
+
94
+ ```
95
+ /cf-task:verify-e2e .code-flow/tasks/2026-03-15/auth-module
96
+
97
+ > 检查子任务状态... 所有任务已完成
98
+ >
99
+ > E2E 场景需要以下环境：
100
+ > - 本地 API 服务 (http://localhost:3000)
101
+ > - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
102
+ >
103
+ > 环境已就绪？(y/N) y
104
+ >
105
+ > 执行 E2E 场景...
106
+ > ✓ E-01: 用户登录流程 (1.2s)
107
+ > ✓ E-02: 权限验证链路 (0.8s)
108
+ >
109
+ > E2E 验收完成！2/2 场景通过
110
+ > 已更新任务状态为 verified
111
+ ```
package/src/adapters/opencode/commands/cf-spec.md CHANGED
@@ -9,6 +9,7 @@ description: 管理 Spec Context、漂移恢复与一次性迁移
9
9
  - `cf-spec migrate --plan <migration-plan.yml>`
10
10
  - `cf-spec context [需求目录]`
11
11
  - `cf-spec refresh [需求目录]`
12
+ - `cf-spec status [需求目录]`
12
13
  - `cf-spec doctor [需求目录]`
13
14
 
14
15
  ## 通用硬门禁
package/src/adapters/opencode/commands/cf-sync.md ADDED
@@ -0,0 +1,29 @@
1
+ ---
2
+ description: 双副本同步：检查漂移并一键部署 canonical 源
3
+ ---
4
+
5
+ # cf-sync
6
+
7
+ 一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
8
+
9
+ - `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
10
+ - `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
11
+ - `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
12
+
13
+ ## 同步配对
14
+
15
+ | canonical 源 | 部署副本 | 同步内容 |
16
+ |---|---|---|
17
+ | `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
18
+ | `src/adapters/claude` | `.claude` | `commands/` |
19
+ | `src/adapters/codex` | `.codex` | `hooks.json` |
20
+ | `src/adapters/codex/skills` | `.agents/skills` | 全部 |
21
+ | `src/adapters/costrict` | `.costrict` | `commands/` |
22
+ | `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
23
+
24
+ ## 规则
25
+
26
+ 1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
27
+ 2. 部署侧独有文件不会被删除（避免误删本地产物）。
28
+ 3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
29
+ 4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。